diff options
Diffstat (limited to 'lib/libsys')
322 files changed, 55804 insertions, 0 deletions
diff --git a/lib/libsys/Makefile b/lib/libsys/Makefile new file mode 100644 index 000000000000..b4b4662ae47f --- /dev/null +++ b/lib/libsys/Makefile @@ -0,0 +1,80 @@ +PACKAGE= clibs +SHLIBDIR?= /lib + +.include <src.opts.mk> + +LIBC_SRCTOP?= ${.CURDIR}/../libc +LIBSYS_SRCTOP?= ${.CURDIR} + +# Pick the current architecture directory for libsys. In general, this is named +# MACHINE_CPUARCH, but some ABIs are different enough to require their own +# libsys, so allow a directory named MACHINE_ARCH to override this (though +# treat powerpc64le and powerpc64 the same). +# Note: This is copied from libc/Makefile +M=${MACHINE_ARCH:S/powerpc64le/powerpc64/} +.if exists(${LIBC_SRCTOP}/${M}) +LIBC_ARCH=${M} +.else +LIBC_ARCH=${MACHINE_CPUARCH} +.endif + +LIB=sys +SHLIB_MAJOR= 7 +WARNS?= 2 +MK_SSP= no + +INCS= libsys.h _libsys.h + +CFLAGS+=-DLIBSYS + +CFLAGS+=-I${LIBSYS_SRCTOP}/include -I${LIBC_SRCTOP}/include +CFLAGS+=-I${LIBSYS_SRCTOP}/${LIBC_ARCH} +CFLAGS+=-I${LIBC_SRCTOP}/${LIBC_ARCH} + +.PATH: ${LIBC_SRCTOP}/string +SRCS+= memcpy.c memset.c strlcpy.c + +CLEANFILES+=tags +INSTALL_PIC_ARCHIVE= +#XXX? BUILD_NOSSP_PIC_ARCHIVE= +PRECIOUSLIB= + +# Use a more efficient TLS model for libc since we can reasonably assume that +# it will be loaded during program startup. +CFLAGS+= -ftls-model=initial-exec + +# +# Link with static libcompiler_rt.a. +# +LDFLAGS+= -nodefaultlibs +LDFLAGS+= -Wl,-Bsymbolic +LIBADD+= compiler_rt + +.if ${MK_SSP} != "no" && \ + (${LIBC_ARCH} == "i386" || ${LIBC_ARCH:Mpowerpc*} != "") +LIBADD+= ssp_nonshared +.endif + +# Define (empty) variables so that make doesn't give substitution +# errors if the included makefiles don't change these: +MDASM= +MIASM= +NOASM= + +SYM_MAPS+= ${LIBSYS_SRCTOP}/Symbol.map +SRCS+= auxv.c \ + interposing_table.c + +.include "${LIBSYS_SRCTOP}/Makefile.sys" + +SYM_MAPS+= ${LIBSYS_SRCTOP}/Symbol.thr.map +.PATH: ${LIBSYS_SRCTOP}/${MACHINE_CPUARCH} +.sinclude "${LIBSYS_SRCTOP}/${MACHINE_CPUARCH}/Makefile.thr" +.if !${SRCS:M_umtx_op_err.S} +SRCS+=_umtx_op_err.c +.endif + +VERSION_DEF=${LIBC_SRCTOP}/Versions.def +SYMBOL_MAPS=${SYM_MAPS} + +.include <bsd.lib.mk> diff --git a/lib/libsys/Makefile.depend b/lib/libsys/Makefile.depend new file mode 100644 index 000000000000..fcba9c64f270 --- /dev/null +++ b/lib/libsys/Makefile.depend @@ -0,0 +1,14 @@ +# Autogenerated - do NOT edit! + +DIRDEPS = \ + include \ + include/xlocale \ + lib/${CSU_DIR} \ + lib/libcompiler_rt \ + + +.include <dirdeps.mk> + +.if ${DEP_RELDIR} == ${_DEP_RELDIR} +# local dependencies - needed for -jN in clean tree +.endif diff --git a/lib/libsys/Makefile.sys b/lib/libsys/Makefile.sys new file mode 100644 index 000000000000..3eb4bf85153d --- /dev/null +++ b/lib/libsys/Makefile.sys @@ -0,0 +1,553 @@ +# Implement symbols common to libc and libsys. +# +# When dynamically linked, the libc symbols are filtered by the actual +# implementations in libsys. When statically linked, both libc and +# libsys contain full implementations to preserve the API of libc.a. +# +# The following variable are programmer-defined: +# +# MDASM Override the default syscall implementation in MIASM +# (from syscall.mk below). Each entry is a source file +# name (e.g., vfork.S). +# Generally defined in <arch>/Makefile.sys. +# NOASM Don't generate system call stubs. Each entry is an +# object file name (e.g., yeild.o). Don't add more of these. +# PSEUDO Generate _<sys> and __sys_<sys> symbols, but not <sys>. +# Each entry is a bare syscall name (e.g., "clock_gettime"). +# INTERPOSED Like PSEUDO, but <sys>.c is added to SRCS. +# Used for syscalls intercepted by the threading library. +# +.PATH: ${LIBSYS_SRCTOP}/${LIBC_ARCH} ${LIBSYS_SRCTOP} + +# Include the generated makefile containing the *complete* list +# of syscall names in MIASM. +.include "${SRCTOP}/sys/sys/syscall.mk" + +# Include machine dependent definitions. +.include "${LIBSYS_SRCTOP}/${LIBC_ARCH}/Makefile.sys" +.if ${LIBC_ARCH} == "i386" || ${LIBC_ARCH} == "amd64" +.include "${LIBSYS_SRCTOP}/x86/Makefile.sys" +.endif + +SRCS+= clock_gettime.c gettimeofday.c __vdso_gettimeofday.c + +# Sources common to both syscall interfaces: +SRCS+= \ + __error.c \ + __getosreldate.c \ + getpagesize.c \ + getpagesizes.c \ + libsys_sigwait.c + +.if ${LIB} == "c" +# Trapping stubs in dynamic libc to be filtered by libsys. +SOBJS+= libc_stubs.pico + +# Link the full implementation of ELF auxargs for static libc. +STATICOBJS+= auxv.o + +STATICOBJS+= interposing_table.o +.endif + +PSEUDO= \ + __realpathat \ + clock_gettime \ + exit \ + getlogin \ + gettimeofday \ + sched_getcpu + +INTERPOSED = \ + accept \ + accept4 \ + aio_suspend \ + clock_nanosleep \ + close \ + connect \ + fcntl \ + fdatasync \ + fsync \ + fork \ + kevent \ + msync \ + nanosleep \ + open \ + openat \ + pdfork \ + poll \ + ppoll \ + pselect \ + ptrace \ + read \ + readv \ + recvfrom \ + recvmsg \ + select \ + sendmsg \ + sendto \ + setcontext \ + sigaction \ + sigprocmask \ + sigsuspend \ + sigtimedwait \ + sigwait \ + sigwaitinfo \ + swapcontext \ + wait4 \ + wait6 \ + write \ + writev + +PSEUDO+= ${INTERPOSED} + +# Add machine dependent asm sources: +SRCS+=${MDASM} + +# Look though the complete list of syscalls (MIASM) for names that are +# not defined with machine dependent implementations (MDASM), not declared +# without a trival <sys> symbol (PSEUDO). Add each syscall that satisfies +# these conditions to the ASM list. +.for _asm in ${MIASM} +.if !${MDASM:R:M${_asm:R}} && !${NOASM:R:M${_asm:R}} && !${PSEUDO:M${_asm:R}} +ASM+=$(_asm) +.endif +.endfor + +SASM= ${ASM:S/.o/.S/} + +SPSEUDO= ${PSEUDO:C/^.*$/_&.S/} + +SRCS+= ${SASM} ${SPSEUDO} + +SYM_MAPS+= ${LIBSYS_SRCTOP}/syscalls.map +SYM_MAPS+= ${LIBSYS_SRCTOP}/Symbol.sys.map +.if exists(${LIBSYS_SRCTOP}/${LIBC_ARCH}/Symbol.sys.map) +SYM_MAPS+= ${LIBSYS_SRCTOP}/${LIBC_ARCH}/Symbol.sys.map +.endif + +# Generated files +CLEANFILES+= ${SASM} ${SPSEUDO} + +NOTE_GNU_STACK='\t.section .note.GNU-stack,"",%%progbits\n' +.if ${MACHINE_CPUARCH} == "aarch64" +FEATURE_NOTE='\#include <sys/elf_common.h>\nGNU_PROPERTY_AARCH64_FEATURE_1_NOTE(GNU_PROPERTY_AARCH64_FEATURE_1_VAL)\n' +.else +FEATURE_NOTE='' +.endif + +${SASM}: + printf '/* %sgenerated by libc/sys/Makefile.inc */\n' @ > ${.TARGET} + printf '#include "compat.h"\n' >> ${.TARGET} + printf '#include "SYS.h"\nRSYSCALL(${.PREFIX})\n' >> ${.TARGET} + printf ${NOTE_GNU_STACK} >>${.TARGET} + printf ${FEATURE_NOTE} >> ${.TARGET} + +${SPSEUDO}: + printf '/* %sgenerated by libc/sys/Makefile.inc */\n' @ > ${.TARGET} + printf '#include "compat.h"\n' >> ${.TARGET} + printf '#include "SYS.h"\nPSEUDO(${.PREFIX:S/_//})\n' \ + >> ${.TARGET} + printf ${NOTE_GNU_STACK} >>${.TARGET} + printf ${FEATURE_NOTE} >> ${.TARGET} + +.if ${LIB} == "sys" +MAN+= abort2.2 \ + accept.2 \ + access.2 \ + acct.2 \ + adjtime.2 \ + aio_cancel.2 \ + aio_error.2 \ + aio_fsync.2 \ + aio_mlock.2 \ + aio_read.2 \ + aio_return.2 \ + aio_suspend.2 \ + aio_waitcomplete.2 \ + aio_write.2 \ + auxv.3 \ + bind.2 \ + bindat.2 \ + brk.2 \ + cap_enter.2 \ + cap_fcntls_limit.2 \ + cap_ioctls_limit.2 \ + cap_rights_limit.2 \ + chdir.2 \ + chflags.2 \ + chmod.2 \ + chown.2 \ + chroot.2 \ + clock_gettime.2 \ + close.2 \ + closefrom.2 \ + connect.2 \ + connectat.2 \ + copy_file_range.2 \ + cpuset.2 \ + cpuset_getaffinity.2 \ + cpuset_getdomain.2 \ + creat.2 \ + dup.2 \ + eventfd.2 \ + execve.2 \ + _exit.2 \ + extattr_get_file.2 \ + fcntl.2 \ + ffclock.2 \ + fhlink.2 \ + fhopen.2 \ + fhreadlink.2 \ + flock.2 \ + fork.2 \ + fspacectl.2 \ + fsync.2 \ + getdirentries.2 \ + getdtablesize.2 \ + getfh.2 \ + getfsstat.2 \ + getgid.2 \ + getgroups.2 \ + getitimer.2 \ + getlogin.2 \ + getloginclass.2 \ + getpeername.2 \ + getpgrp.2 \ + getpid.2 \ + getpriority.2 \ + getrandom.2 \ + getrlimit.2 \ + getrlimitusage.2 \ + getrusage.2 \ + getsid.2 \ + getsockname.2 \ + getsockopt.2 \ + gettimeofday.2 \ + getuid.2 \ + inotify.2 \ + intro.2 \ + ioctl.2 \ + issetugid.2 \ + jail.2 \ + kcmp.2 \ + kenv.2 \ + kill.2 \ + kldfind.2 \ + kldfirstmod.2 \ + kldload.2 \ + kldnext.2 \ + kldstat.2 \ + kldsym.2 \ + kldunload.2 \ + kqueue.2 \ + ktrace.2 \ + link.2 \ + lio_listio.2 \ + listen.2 \ + lseek.2 \ + madvise.2 \ + membarrier.2 \ + mincore.2 \ + minherit.2 \ + mkdir.2 \ + mkfifo.2 \ + mknod.2 \ + mlock.2 \ + mlockall.2 \ + mmap.2 \ + modfind.2 \ + modnext.2 \ + modstat.2 \ + mount.2 \ + mprotect.2 \ + mq_close.2 \ + mq_getattr.2 \ + mq_notify.2 \ + mq_open.2 \ + mq_receive.2 \ + mq_send.2 \ + mq_setattr.2 \ + mq_unlink.2 \ + msgctl.2 \ + msgget.2 \ + msgrcv.2 \ + msgsnd.2 \ + msync.2 \ + munmap.2 \ + nanosleep.2 \ + nfssvc.2 \ + ntp_adjtime.2 \ + open.2 \ + pathconf.2 \ + pdfork.2 \ + pipe.2 \ + poll.2 \ + posix_fadvise.2 \ + posix_fallocate.2 \ + posix_openpt.2 \ + procctl.2 \ + profil.2 \ + pselect.2 \ + ptrace.2 \ + quotactl.2 \ + rctl_add_rule.2 \ + read.2 \ + readlink.2 \ + reboot.2 \ + recv.2 \ + rename.2 \ + revoke.2 \ + rfork.2 \ + rmdir.2 \ + rtprio.2 \ + sched_get_priority_max.2 \ + sched_getcpu.3 \ + sched_setparam.2 \ + sched_setscheduler.2 \ + sched_yield.2 \ + sctp_generic_recvmsg.2 \ + sctp_generic_sendmsg.2 \ + sctp_peeloff.2 \ + select.2 \ + semctl.2 \ + semget.2 \ + semop.2 \ + send.2 \ + setcred.2 \ + setfib.2 \ + sendfile.2 \ + setgroups.2 \ + setpgid.2 \ + setregid.2 \ + setresuid.2 \ + setreuid.2 \ + setsid.2 \ + setuid.2 \ + shmat.2 \ + shmctl.2 \ + shmget.2 \ + shm_open.2 \ + shutdown.2 \ + sigaction.2 \ + sigaltstack.2 \ + sigfastblock.2 \ + sigpending.2 \ + sigprocmask.2 \ + sigqueue.2 \ + sigreturn.2 \ + sigstack.2 \ + sigsuspend.2 \ + sigwait.2 \ + sigwaitinfo.2 \ + socket.2 \ + socketpair.2 \ + stat.2 \ + statfs.2 \ + swapon.2 \ + symlink.2 \ + sync.2 \ + sysarch.2 \ + syscall.2 \ + thr_exit.2 \ + thr_kill.2 \ + thr_new.2 \ + thr_self.2 \ + thr_set_name.2 \ + thr_suspend.2 \ + thr_wake.2 \ + timer_create.2 \ + timer_delete.2 \ + timer_settime.2 \ + timerfd.2 \ + truncate.2 \ + umask.2 \ + undelete.2 \ + unlink.2 \ + utimensat.2 \ + utimes.2 \ + utrace.2 \ + uuidgen.2 \ + vfork.2 \ + wait.2 \ + write.2 \ + _umtx_op.2 + +MAN+= \ + getpagesize.3 \ + getpagesizes.3 \ + lockf.3 \ + rfork_thread.3 \ + sleep.3 \ + usleep.3 + +MLINKS+=aio_read.2 aio_readv.2 \ + aio_read.2 aio_read2.2 +MLINKS+=aio_write.2 aio_writev.2 \ + aio_write.2 aio_write2.2 +MLINKS+=accept.2 accept4.2 +MLINKS+=access.2 eaccess.2 \ + access.2 faccessat.2 +MLINKS+=auxv.3 elf_aux_info.3 +MLINKS+=brk.2 sbrk.2 +MLINKS+=cap_enter.2 cap_getmode.2 +MLINKS+=cap_fcntls_limit.2 cap_fcntls_get.2 +MLINKS+=cap_ioctls_limit.2 cap_ioctls_get.2 +MLINKS+=chdir.2 fchdir.2 +MLINKS+=chflags.2 chflagsat.2 \ + chflags.2 fchflags.2 \ + chflags.2 lchflags.2 +MLINKS+=chmod.2 fchmod.2 \ + chmod.2 fchmodat.2 \ + chmod.2 lchmod.2 +MLINKS+=chown.2 fchown.2 \ + chown.2 fchownat.2 \ + chown.2 lchown.2 +MLINKS+=chroot.2 fchroot.2 +MLINKS+=clock_gettime.2 clock_getres.2 \ + clock_gettime.2 clock_settime.2 +MLINKS+=closefrom.2 close_range.2 +MLINKS+=nanosleep.2 clock_nanosleep.2 +MLINKS+=cpuset.2 cpuset_getid.2 \ + cpuset.2 cpuset_setid.2 +MLINKS+=cpuset_getaffinity.2 cpuset_setaffinity.2 +MLINKS+=cpuset_getdomain.2 cpuset_setdomain.2 +MLINKS+=dup.2 dup2.2 +MLINKS+=eventfd.2 eventfd_read.3 \ + eventfd.2 eventfd_write.3 +MLINKS+=execve.2 fexecve.2 +MLINKS+=extattr_get_file.2 extattr.2 \ + extattr_get_file.2 extattr_delete_fd.2 \ + extattr_get_file.2 extattr_delete_file.2 \ + extattr_get_file.2 extattr_delete_link.2 \ + extattr_get_file.2 extattr_get_fd.2 \ + extattr_get_file.2 extattr_get_link.2 \ + extattr_get_file.2 extattr_list_fd.2 \ + extattr_get_file.2 extattr_list_file.2 \ + extattr_get_file.2 extattr_list_link.2 \ + extattr_get_file.2 extattr_set_fd.2 \ + extattr_get_file.2 extattr_set_file.2 \ + extattr_get_file.2 extattr_set_link.2 +MLINKS+=ffclock.2 ffclock_getcounter.2 \ + ffclock.2 ffclock_getestimate.2 \ + ffclock.2 ffclock_setestimate.2 +MLINKS+=fhlink.2 fhlinkat.2 +MLINKS+=fhopen.2 fhstat.2 fhopen.2 fhstatfs.2 +MLINKS+=fork.2 _Fork.2 +MLINKS+=fsync.2 fdatasync.2 +MLINKS+=getdirentries.2 getdents.2 +MLINKS+=getfh.2 lgetfh.2 \ + getfh.2 getfhat.2 +MLINKS+=getgid.2 getegid.2 +MLINKS+=getitimer.2 setitimer.2 +MLINKS+=getlogin.2 getlogin_r.3 +MLINKS+=getlogin.2 setlogin.2 +MLINKS+=getloginclass.2 setloginclass.2 +MLINKS+=getpgrp.2 getpgid.2 +MLINKS+=getpid.2 getppid.2 +MLINKS+=getpriority.2 setpriority.2 +MLINKS+=getrlimit.2 setrlimit.2 +MLINKS+=getsockopt.2 setsockopt.2 +MLINKS+=gettimeofday.2 settimeofday.2 +MLINKS+=getuid.2 geteuid.2 +MLINKS+=inotify.2 inotify_init.2 \ + inotify.2 inotify_init1.2 \ + inotify.2 inotify_add_watch.2 \ + inotify.2 inotify_add_watch_at.2 \ + inotify.2 inotify_rm_watch.2 +MLINKS+=intro.2 errno.2 +MLINKS+=jail.2 jail_attach.2 \ + jail.2 jail_get.2 \ + jail.2 jail_remove.2 \ + jail.2 jail_set.2 +MLINKS+=kldunload.2 kldunloadf.2 +MLINKS+=kqueue.2 kevent.2 \ + kqueue.2 kqueue1.2 \ + kqueue.2 kqueuex.2 \ + kqueue.2 EV_SET.3 +MLINKS+=link.2 linkat.2 +MLINKS+=madvise.2 posix_madvise.2 +MLINKS+=mkdir.2 mkdirat.2 +MLINKS+=mkfifo.2 mkfifoat.2 +MLINKS+=mknod.2 mknodat.2 +MLINKS+=mlock.2 munlock.2 +MLINKS+=mlockall.2 munlockall.2 +MLINKS+=modnext.2 modfnext.2 +MLINKS+=mount.2 nmount.2 \ + mount.2 unmount.2 +MLINKS+=mq_receive.2 mq_timedreceive.2 +MLINKS+=mq_send.2 mq_timedsend.2 +MLINKS+=ntp_adjtime.2 ntp_gettime.2 +MLINKS+=open.2 openat.2 +MLINKS+=pathconf.2 fpathconf.2 +MLINKS+=pathconf.2 lpathconf.2 +MLINKS+=pdfork.2 pdgetpid.2\ + pdfork.2 pdkill.2 +MLINKS+=pipe.2 pipe2.2 +MLINKS+=poll.2 ppoll.2 +MLINKS+=rctl_add_rule.2 rctl_get_limits.2 \ + rctl_add_rule.2 rctl_get_racct.2 \ + rctl_add_rule.2 rctl_get_rules.2 \ + rctl_add_rule.2 rctl_remove_rule.2 +MLINKS+=read.2 pread.2 \ + read.2 preadv.2 \ + read.2 readv.2 +MLINKS+=readlink.2 readlinkat.2 +MLINKS+=recv.2 recvfrom.2 \ + recv.2 recvmmsg.2 \ + recv.2 recvmsg.2 +MLINKS+=rename.2 renameat.2 +MLINKS+=rtprio.2 rtprio_thread.2 +MLINKS+=sched_get_priority_max.2 sched_get_priority_min.2 \ + sched_get_priority_max.2 sched_rr_get_interval.2 +MLINKS+=sched_setparam.2 sched_getparam.2 +MLINKS+=sched_setscheduler.2 sched_getscheduler.2 +MLINKS+=sctp_generic_sendmsg.2 sctp_generic_sendmsg_iov.2 +MLINKS+=select.2 FD_CLR.3 \ + select.2 FD_ISSET.3 \ + select.2 FD_SET.3 \ + select.2 FD_ZERO.3 +MLINKS+=send.2 sendmmsg.2 \ + send.2 sendmsg.2 \ + send.2 sendto.2 +MLINKS+=setpgid.2 setpgrp.2 +MLINKS+=setresuid.2 getresgid.2 \ + setresuid.2 getresuid.2 \ + setresuid.2 setresgid.2 +MLINKS+=setuid.2 setegid.2 \ + setuid.2 seteuid.2 \ + setuid.2 setgid.2 +MLINKS+=shmat.2 shmdt.2 +MLINKS+=shm_open.2 memfd_create.3 \ + shm_open.2 shm_create_largepage.3 \ + shm_open.2 shm_unlink.2 \ + shm_open.2 shm_rename.2 +MLINKS+=sigwaitinfo.2 sigtimedwait.2 +MLINKS+=stat.2 fstat.2 \ + stat.2 fstatat.2 \ + stat.2 lstat.2 +MLINKS+=statfs.2 fstatfs.2 +MLINKS+=swapon.2 swapoff.2 +MLINKS+=symlink.2 symlinkat.2 +MLINKS+=syscall.2 __syscall.2 +MLINKS+=timer_settime.2 timer_getoverrun.2 \ + timer_settime.2 timer_gettime.2 +MLINKS+=timerfd.2 timerfd_create.2 \ + timerfd.2 timerfd_gettime.2 \ + timerfd.2 timerfd_settime.2 +MLINKS+=thr_kill.2 thr_kill2.2 +MLINKS+=truncate.2 ftruncate.2 +MLINKS+=unlink.2 unlinkat.2 +MLINKS+=unlink.2 funlinkat.2 +MLINKS+=utimensat.2 futimens.2 +MLINKS+=utimes.2 futimes.2 \ + utimes.2 futimesat.2 \ + utimes.2 lutimes.2 +MLINKS+=wait.2 wait3.2 \ + wait.2 wait4.2 \ + wait.2 waitpid.2 \ + wait.2 waitid.2 \ + wait.2 wait6.2 +MLINKS+=write.2 pwrite.2 \ + write.2 pwritev.2 \ + write.2 writev.2 +.endif # ${LIB} == "sys" diff --git a/lib/libsys/Symbol.map b/lib/libsys/Symbol.map new file mode 100644 index 000000000000..eb71c813ae86 --- /dev/null +++ b/lib/libsys/Symbol.map @@ -0,0 +1,13 @@ +FBSDprivate_1.0 { + __elf_aux_vector; + __libsys_errno; + __getosreldate; + __libsys_interposing_slot; + _elf_aux_info; + freebsd11_fstat; + freebsd11_fstatat; + freebsd11_getfsstat; + freebsd11_lstat; + freebsd11_stat; + freebsd11_statfs; +}; diff --git a/lib/libsys/Symbol.sys.map b/lib/libsys/Symbol.sys.map new file mode 100644 index 000000000000..45e0160100af --- /dev/null +++ b/lib/libsys/Symbol.sys.map @@ -0,0 +1,396 @@ +/* + * It'd be nice to automatically generate the syscall symbols, but we + * don't know to what version they will eventually belong to, so for now + * it has to be manual. + */ +FBSD_1.0 { + __acl_aclcheck_fd; + __acl_aclcheck_file; + __acl_aclcheck_link; + __acl_delete_fd; + __acl_delete_file; + __acl_delete_link; + __acl_get_fd; + __acl_get_file; + __acl_get_link; + __acl_set_fd; + __acl_set_file; + __acl_set_link; + __getcwd; + __mac_execve; + __mac_get_fd; + __mac_get_file; + __mac_get_link; + __mac_get_pid; + __mac_get_proc; + __mac_set_fd; + __mac_set_file; + __mac_set_link; + __mac_set_proc; + __setugid; + __syscall; + __sysctl; + _exit; + _umtx_op; + abort2; + access; + acct; + adjtime; + aio_cancel; + aio_error; + aio_fsync; + aio_read; + aio_return; + aio_waitcomplete; + aio_write; + audit; + auditctl; + auditon; + bind; + chdir; + chflags; + chmod; + chown; + chroot; + clock_getres; + clock_gettime; + clock_settime; + dup; + dup2; + eaccess; + execve; + extattr_delete_fd; + extattr_delete_file; + extattr_delete_link; + extattr_get_fd; + extattr_get_file; + extattr_get_link; + extattr_list_fd; + extattr_list_file; + extattr_list_link; + extattr_set_fd; + extattr_set_file; + extattr_set_link; + extattrctl; + fchdir; + fchflags; + fchmod; + fchown; + fhopen; + flock; + fpathconf; + futimes; + getaudit; + getaudit_addr; + getauid; + getcontext; + getdtablesize; + getegid; + geteuid; + getfh; + getgid; + getgroups; + getitimer; + getpagesize; + getpeername; + getpgid; + getpgrp; + getpid; + getppid; + getpriority; + getresgid; + getresuid; + getrlimit; + getrusage; + getsid; + getsockname; + getsockopt; + gettimeofday; + getuid; + ioctl; + issetugid; + jail; + jail_attach; + kenv; + kill; + kldfind; + kldfirstmod; + kldload; + kldnext; + kldstat; + kldsym; + kldunload; + kldunloadf; + kqueue; + kmq_notify; /* Do we want these to be public interfaces? */ + kmq_open; /* librt uses them to provide mq_xxx. */ + kmq_setattr; + kmq_timedreceive; + kmq_timedsend; + kmq_unlink; + ksem_close; + ksem_destroy; + ksem_getvalue; + ksem_init; + ksem_open; + ksem_post; + ksem_timedwait; + ksem_trywait; + ksem_unlink; + ksem_wait; + ktrace; + lchflags; + lchmod; + lchown; + lgetfh; + link; + lio_listio; + listen; + lutimes; + mac_syscall; + madvise; + mincore; + minherit; + mkdir; + mkfifo; + mlock; + mlockall; + modfind; + modfnext; + modnext; + modstat; + mount; + mprotect; + msgget; + msgrcv; + msgsnd; + msgsys; + munlock; + munlockall; + munmap; + nfssvc; + nmount; + ntp_adjtime; + ntp_gettime; + pathconf; + posix_openpt; + preadv; + profil; + pwritev; + quotactl; + readlink; + reboot; + rename; + revoke; + rfork; + rmdir; + rtprio; + rtprio_thread; + sched_get_priority_max; + sched_get_priority_min; + sched_getparam; + sched_getscheduler; + sched_rr_get_interval; + sched_setparam; + sched_setscheduler; + sched_yield; + semget; + semop; + semsys; + sendfile; + setaudit; + setaudit_addr; + setauid; + setegid; + seteuid; + setgid; + setgroups; + setitimer; + setlogin; + setpgid; + setpriority; + setregid; + setresgid; + setresuid; + setreuid; + setrlimit; + setsid; + setsockopt; + settimeofday; + setuid; + shm_unlink; + shmat; + shmdt; + shmget; + shmsys; + shutdown; + sigaltstack; + sigpending; + sigqueue; + sigreturn; + socket; + socketpair; + swapon; + symlink; + sync; + sysarch; + syscall; + thr_create; + thr_exit; + thr_kill; + thr_kill2; + thr_new; + thr_self; + thr_set_name; + thr_suspend; + thr_wake; + ktimer_create; /* Do we want these to be public interfaces? */ + ktimer_delete; /* librt uses them to provide timer_xxx. */ + ktimer_getoverrun; + ktimer_gettime; + ktimer_settime; + umask; + undelete; + unlink; + unmount; + utimes; + utrace; + uuidgen; + vfork; + + __error; + ftruncate; + lseek; + mmap; + pread; + pwrite; + truncate; +}; + +FBSD_1.1 { + __semctl; + cpuset; + cpuset_getid; + cpuset_setid; + cpuset_getaffinity; + cpuset_setaffinity; + faccessat; + fchmodat; + fchownat; + fexecve; + futimesat; + jail_get; + jail_set; + jail_remove; + linkat; + lpathconf; + mkdirat; + mkfifoat; + msgctl; + readlinkat; + renameat; + setfib; + shmctl; + symlinkat; + unlinkat; +}; + +FBSD_1.2 { + cap_enter; + cap_getmode; + getloginclass; + getpagesizes; + pdgetpid; + pdkill; + posix_fallocate; + rctl_get_racct; + rctl_get_rules; + rctl_get_limits; + rctl_add_rule; + rctl_remove_rule; + setloginclass; +}; + +FBSD_1.3 { + aio_mlock; + bindat; + cap_fcntls_get; + cap_fcntls_limit; + cap_ioctls_get; + cap_ioctls_limit; + __cap_rights_get; + cap_rights_limit; + chflagsat; + clock_getcpuclockid2; + connectat; + ffclock_getcounter; + ffclock_getestimate; + ffclock_setestimate; + pipe2; + posix_fadvise; + procctl; +}; + +FBSD_1.4 { + futimens; + utimensat; +}; + +FBSD_1.5 { + elf_aux_info; + fhstat; + fhstatfs; + fstat; + fstatat; + fstatfs; + getdirentries; + getfsstat; + getrandom; + mknodat; + statfs; + cpuset_getdomain; + cpuset_setdomain; +}; + +FBSD_1.6 { + __sysctlbyname; + aio_readv; + aio_writev; + close_range; + copy_file_range; + fhlink; + fhlinkat; + fhreadlink; + getfhat; + funlinkat; + shm_rename; +}; + +FBSD_1.7 { + fspacectl; + kqueuex; + membarrier; + sched_getcpu; + swapoff; + timerfd_create; + timerfd_gettime; + timerfd_settime; +}; + +FBSD_1.8 { + exterrctl; + fchroot; + getrlimitusage; + inotify_add_watch_at; + inotify_rm_watch; + kcmp; + setcred; +}; + +FBSDprivate_1.0 { + /* Add entries in sort(1) order */ + __set_error_selector; + __sigwait; + nlm_syscall; + rpctls_syscall; +}; diff --git a/lib/libsys/Symbol.thr.map b/lib/libsys/Symbol.thr.map new file mode 100644 index 000000000000..a245de2e547a --- /dev/null +++ b/lib/libsys/Symbol.thr.map @@ -0,0 +1,3 @@ +FBSDprivate_1.0 { + _umtx_op_err; +}; diff --git a/lib/libsys/__error.c b/lib/libsys/__error.c new file mode 100644 index 000000000000..41016e9a1ed2 --- /dev/null +++ b/lib/libsys/__error.c @@ -0,0 +1,57 @@ +/*- + * SPDX-License-Identifier: BSD-3-Clause + * + * Copyright (c) 1997 John Birrell <jb@cimlogic.com.au>. + * All rights reserved. + * + * 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. + * 3. Neither the name of the author nor the names of any co-contributors + * may be used to endorse or promote products derived from this software + * without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 REGENTS 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. + */ + +#include "libc_private.h" + +int __libsys_errno; +#ifdef LIBSYS +__sym_compat(errno, __libsys_errno, FBSD_1.0); +#endif + +static int * +__error_unthreaded(void) +{ + return (&__libsys_errno); +} + +static int *(*__error_selector)(void) = __error_unthreaded; + +void +__set_error_selector(int *(*arg)(void)) +{ + __error_selector = arg; +} + +int * +__error(void) +{ + return (__error_selector()); +} diff --git a/lib/libsys/__getosreldate.c b/lib/libsys/__getosreldate.c new file mode 100644 index 000000000000..0bb2efd2ba6a --- /dev/null +++ b/lib/libsys/__getosreldate.c @@ -0,0 +1,53 @@ +/*- + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (c) 2007 Peter Wemm + * + * 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. + */ + +#include <sys/param.h> +#include <sys/sysctl.h> +#include <errno.h> +#include <link.h> +#include "libc_private.h" + +/* + * This is private to libc. It is intended for wrapping syscall stubs in order + * to avoid having to put SIGSYS signal handlers in place to test for presence + * of new syscalls. This caches the result in order to be as quick as possible. + * + * Use getosreldate(3) for public use as it respects the $OSVERSION environment + * variable. + */ + +int +__getosreldate(void) +{ + static int osreldate; + + if (osreldate != 0) + return (osreldate); + + (void)_elf_aux_info(AT_OSRELDATE, &osreldate, sizeof(osreldate)); + return (osreldate); +} diff --git a/lib/libsys/__vdso_gettimeofday.c b/lib/libsys/__vdso_gettimeofday.c new file mode 100644 index 000000000000..273eeb58d195 --- /dev/null +++ b/lib/libsys/__vdso_gettimeofday.c @@ -0,0 +1,196 @@ +/*- + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (c) 2012 Konstantin Belousov <kib@FreeBSD.org> + * + * 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. + */ + +#include <sys/elf.h> +#include <sys/time.h> +#include <sys/vdso.h> +#include <errno.h> +#include <stdbool.h> +#include <strings.h> +#include <time.h> +#include <machine/atomic.h> +#include "libc_private.h" + +static int +tc_delta(const struct vdso_timehands *th, u_int *delta) +{ + int error; + u_int tc; + + error = __vdso_gettc(th, &tc); + if (error == 0) + *delta = (tc - th->th_offset_count) & th->th_counter_mask; + return (error); +} + +/* + * Calculate the absolute or boot-relative time from the + * machine-specific fast timecounter and the published timehands + * structure read from the shared page. + * + * The lockless reading scheme is similar to the one used to read the + * in-kernel timehands, see sys/kern/kern_tc.c:binuptime(). This code + * is based on the kernel implementation. + */ +static int +binuptime(struct bintime *bt, struct vdso_timekeep *tk, bool abs) +{ + struct vdso_timehands *th; + uint32_t curr, gen; + uint64_t scale, x; + u_int delta, scale_bits; + int error; + + do { + if (!tk->tk_enabled) + return (ENOSYS); + + curr = atomic_load_acq_32(&tk->tk_current); + th = &tk->tk_th[curr]; + gen = atomic_load_acq_32(&th->th_gen); + *bt = th->th_offset; + error = tc_delta(th, &delta); + if (error == EAGAIN) + continue; + if (error != 0) + return (error); + scale = th->th_scale; +#ifdef _LP64 + scale_bits = flsl(scale); +#else + scale_bits = flsll(scale); +#endif + if (__predict_false(scale_bits + fls(delta) > 63)) { + x = (scale >> 32) * delta; + scale &= 0xffffffff; + bt->sec += x >> 32; + bintime_addx(bt, x << 32); + } + bintime_addx(bt, scale * delta); + if (abs) + bintime_add(bt, &th->th_boottime); + + /* + * Ensure that the load of th_offset is completed + * before the load of th_gen. + */ + atomic_thread_fence_acq(); + } while (curr != tk->tk_current || gen == 0 || gen != th->th_gen); + return (0); +} + +static int +getnanouptime(struct bintime *bt, struct vdso_timekeep *tk) +{ + struct vdso_timehands *th; + uint32_t curr, gen; + + do { + if (!tk->tk_enabled) + return (ENOSYS); + + curr = atomic_load_acq_32(&tk->tk_current); + th = &tk->tk_th[curr]; + gen = atomic_load_acq_32(&th->th_gen); + *bt = th->th_offset; + + /* + * Ensure that the load of th_offset is completed + * before the load of th_gen. + */ + atomic_thread_fence_acq(); + } while (curr != tk->tk_current || gen == 0 || gen != th->th_gen); + return (0); +} + +static struct vdso_timekeep *tk; + +#pragma weak __vdso_gettimeofday +int +__vdso_gettimeofday(struct timeval *tv, struct timezone *tz) +{ + struct bintime bt; + int error; + + if (tz != NULL) + return (ENOSYS); + if (tk == NULL) { + error = __vdso_gettimekeep(&tk); + if (error != 0 || tk == NULL) + return (ENOSYS); + } + if (tk->tk_ver != VDSO_TK_VER_CURR) + return (ENOSYS); + error = binuptime(&bt, tk, true); + if (error != 0) + return (error); + bintime2timeval(&bt, tv); + return (0); +} + +#pragma weak __vdso_clock_gettime +int +__vdso_clock_gettime(clockid_t clock_id, struct timespec *ts) +{ + struct bintime bt; + int error; + + if (tk == NULL) { + error = _elf_aux_info(AT_TIMEKEEP, &tk, sizeof(tk)); + if (error != 0 || tk == NULL) + return (ENOSYS); + } + if (tk->tk_ver != VDSO_TK_VER_CURR) + return (ENOSYS); + switch (clock_id) { + case CLOCK_REALTIME: + case CLOCK_REALTIME_PRECISE: + case CLOCK_REALTIME_FAST: + case CLOCK_SECOND: + error = binuptime(&bt, tk, true); + break; + case CLOCK_MONOTONIC: + case CLOCK_MONOTONIC_PRECISE: + case CLOCK_UPTIME: + case CLOCK_UPTIME_PRECISE: + error = binuptime(&bt, tk, false); + break; + case CLOCK_MONOTONIC_FAST: + case CLOCK_UPTIME_FAST: + error = getnanouptime(&bt, tk); + break; + default: + error = ENOSYS; + break; + } + if (error != 0) + return (error); + bintime2timespec(&bt, ts); + if (clock_id == CLOCK_SECOND) + ts->tv_nsec = 0; + return (0); +} diff --git a/lib/libsys/_exit.2 b/lib/libsys/_exit.2 new file mode 100644 index 000000000000..6f038f79f6ea --- /dev/null +++ b/lib/libsys/_exit.2 @@ -0,0 +1,122 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd September 8, 2016 +.Dt EXIT 2 +.Os +.Sh NAME +.Nm _exit +.Nd terminate the calling process +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft void +.Fn _exit "int status" +.Sh DESCRIPTION +The +.Fn _exit +system call +terminates a process with the following consequences: +.Bl -bullet +.It +All of the descriptors open in the calling process are closed. +This may entail delays, for example, waiting for output to drain; +a process in this state may not be killed, as it is already dying. +.It +If the parent process of the calling process has an outstanding +.Xr wait 2 +call +or catches the +.Dv SIGCHLD +signal, +it is notified of the calling process's termination and +the +.Fa status +is set as defined by +.Xr wait 2 . +.It +The parent process-ID of all of the calling process's existing child +processes are set to the process-ID of the calling process's reaper; +the reaper (normally the initialization process) +inherits each of these processes +(see +.Xr procctl 2 , +.Xr init 8 +and the +.Sx DEFINITIONS +section of +.Xr intro 2 ) . +.It +If the termination of the process causes any process group +to become orphaned (usually because the parents of all members +of the group have now exited; see +.Dq orphaned process group +in +.Xr intro 2 ) , +and if any member of the orphaned group is stopped, +the +.Dv SIGHUP +signal and the +.Dv SIGCONT +signal are sent to all members of the newly-orphaned process group. +.It +If the process is a controlling process (see +.Xr intro 2 ) , +the +.Dv SIGHUP +signal is sent to the foreground process group of the controlling terminal, +and all current access to the controlling terminal is revoked. +.El +.Pp +Most C programs call the library routine +.Xr exit 3 , +which flushes buffers, closes streams, unlinks temporary files, etc., +before +calling +.Fn _exit . +.Sh RETURN VALUES +The +.Fn _exit +system call +can never return. +.Sh SEE ALSO +.Xr fork 2 , +.Xr sigaction 2 , +.Xr wait 2 , +.Xr exit 3 , +.Xr init 8 +.Sh STANDARDS +The +.Fn _exit +system call is expected to conform to +.St -p1003.1-90 . +.Sh HISTORY +The +.Fn _exit +function appeared in +.At v7 . diff --git a/lib/libsys/_libsys.h b/lib/libsys/_libsys.h new file mode 100644 index 000000000000..7a1685cca2d1 --- /dev/null +++ b/lib/libsys/_libsys.h @@ -0,0 +1,877 @@ +/* + * Public system call stubs provided by libsys. + * + * Do not use directly, include <libsys.h> instead. + * + * DO NOT EDIT-- this file is automatically @generated. + */ + +#ifndef __LIBSYS_H_ +#define __LIBSYS_H_ + +#include <sys/_cpuset.h> +#include <sys/_domainset.h> +#include <sys/_ffcounter.h> +#include <sys/_semaphore.h> +#include <sys/_sigaltstack.h> +#include <machine/ucontext.h> /* for mcontext_t */ +#include <sys/_ucontext.h> +#include <sys/wait.h> + +struct __siginfo; +struct __ucontext; +struct __wrusage; +struct acl; +struct aiocb; +struct auditinfo; +struct auditinfo_addr; +struct ffclock_estimate; +struct fhandle; +struct iovec; +struct itimerspec; +struct itimerval; +struct jail; +struct kevent; +struct kld_file_stat; +struct mac; +struct module_stat; +struct mq_attr; +struct msghdr; +struct msqid_ds; +struct ntptimeval; +struct pollfd; +struct rlimit; +struct rtprio; +struct rusage; +struct sched_param; +struct sctp_sndrcvinfo; +struct sembuf; +struct setcred; +struct sf_hdtr; +struct shmid_ds; +struct sigaction; +struct sigaltstack; +struct sigevent; +struct sockaddr; +struct spacectl_range; +struct stat; +struct statfs; +struct thr_param; +struct timespec; +struct timeval; +struct timex; +struct timezone; +struct uuid; +union semun; + +__BEGIN_DECLS +typedef void (__sys_exit_t)(int); +typedef int (__sys_fork_t)(void); +typedef ssize_t (__sys_read_t)(int, void *, size_t); +typedef ssize_t (__sys_write_t)(int, const void *, size_t); +typedef int (__sys_open_t)(const char *, int, mode_t); +typedef int (__sys_close_t)(int); +typedef int (__sys_wait4_t)(int, int *, int, struct rusage *); +typedef int (__sys_link_t)(const char *, const char *); +typedef int (__sys_unlink_t)(const char *); +typedef int (__sys_chdir_t)(const char *); +typedef int (__sys_fchdir_t)(int); +typedef int (__sys_chmod_t)(const char *, mode_t); +typedef int (__sys_chown_t)(const char *, int, int); +typedef void * (__sys_break_t)(char *); +typedef pid_t (__sys_getpid_t)(void); +typedef int (__sys_mount_t)(const char *, const char *, int, void *); +typedef int (__sys_unmount_t)(const char *, int); +typedef int (__sys_setuid_t)(uid_t); +typedef uid_t (__sys_getuid_t)(void); +typedef uid_t (__sys_geteuid_t)(void); +typedef int (__sys_ptrace_t)(int, pid_t, caddr_t, int); +typedef ssize_t (__sys_recvmsg_t)(int, struct msghdr *, int); +typedef ssize_t (__sys_sendmsg_t)(int, const struct msghdr *, int); +typedef ssize_t (__sys_recvfrom_t)(int, void *, size_t, int, struct sockaddr *, __socklen_t *); +typedef int (__sys_accept_t)(int, struct sockaddr *, __socklen_t *); +typedef int (__sys_getpeername_t)(int, struct sockaddr *, __socklen_t *); +typedef int (__sys_getsockname_t)(int, struct sockaddr *, __socklen_t *); +typedef int (__sys_access_t)(const char *, int); +typedef int (__sys_chflags_t)(const char *, u_long); +typedef int (__sys_fchflags_t)(int, u_long); +typedef int (__sys_sync_t)(void); +typedef int (__sys_kill_t)(int, int); +typedef pid_t (__sys_getppid_t)(void); +typedef int (__sys_dup_t)(u_int); +typedef gid_t (__sys_getegid_t)(void); +typedef int (__sys_profil_t)(char *, size_t, size_t, u_int); +typedef int (__sys_ktrace_t)(const char *, int, int, int); +typedef gid_t (__sys_getgid_t)(void); +typedef int (__sys_getlogin_t)(char *, u_int); +typedef int (__sys_setlogin_t)(const char *); +typedef int (__sys_acct_t)(const char *); +typedef int (__sys_sigaltstack_t)(const struct sigaltstack *, struct sigaltstack *); +typedef int (__sys_ioctl_t)(int, u_long, char *); +typedef int (__sys_reboot_t)(int); +typedef int (__sys_revoke_t)(const char *); +typedef int (__sys_symlink_t)(const char *, const char *); +typedef ssize_t (__sys_readlink_t)(const char *, char *, size_t); +typedef int (__sys_execve_t)(const char *, char **, char **); +typedef mode_t (__sys_umask_t)(mode_t); +typedef int (__sys_chroot_t)(const char *); +typedef int (__sys_msync_t)(void *, size_t, int); +typedef int (__sys_vfork_t)(void); +typedef int (__sys_munmap_t)(void *, size_t); +typedef int (__sys_mprotect_t)(void *, size_t, int); +typedef int (__sys_madvise_t)(void *, size_t, int); +typedef int (__sys_mincore_t)(const void *, size_t, char *); +typedef int (__sys_getgroups_t)(int, gid_t *); +typedef int (__sys_setgroups_t)(int, const gid_t *); +typedef int (__sys_getpgrp_t)(void); +typedef int (__sys_setpgid_t)(int, int); +typedef int (__sys_setitimer_t)(int, const struct itimerval *, struct itimerval *); +typedef int (__sys_swapon_t)(const char *); +typedef int (__sys_getitimer_t)(int, struct itimerval *); +typedef int (__sys_getdtablesize_t)(void); +typedef int (__sys_dup2_t)(u_int, u_int); +typedef int (__sys_fcntl_t)(int, int, intptr_t); +typedef int (__sys_select_t)(int, fd_set *, fd_set *, fd_set *, struct timeval *); +typedef int (__sys_fsync_t)(int); +typedef int (__sys_setpriority_t)(int, int, int); +typedef int (__sys_socket_t)(int, int, int); +typedef int (__sys_connect_t)(int, const struct sockaddr *, __socklen_t); +typedef int (__sys_getpriority_t)(int, int); +typedef int (__sys_bind_t)(int, const struct sockaddr *, __socklen_t); +typedef int (__sys_setsockopt_t)(int, int, int, const void *, __socklen_t); +typedef int (__sys_listen_t)(int, int); +typedef int (__sys_gettimeofday_t)(struct timeval *, struct timezone *); +typedef int (__sys_getrusage_t)(int, struct rusage *); +typedef int (__sys_getsockopt_t)(int, int, int, void *, __socklen_t *); +typedef ssize_t (__sys_readv_t)(int, const struct iovec *, u_int); +typedef ssize_t (__sys_writev_t)(int, const struct iovec *, u_int); +typedef int (__sys_settimeofday_t)(const struct timeval *, const struct timezone *); +typedef int (__sys_fchown_t)(int, int, int); +typedef int (__sys_fchmod_t)(int, mode_t); +typedef int (__sys_setreuid_t)(int, int); +typedef int (__sys_setregid_t)(int, int); +typedef int (__sys_rename_t)(const char *, const char *); +typedef int (__sys_flock_t)(int, int); +typedef int (__sys_mkfifo_t)(const char *, mode_t); +typedef ssize_t (__sys_sendto_t)(int, const void *, size_t, int, const struct sockaddr *, __socklen_t); +typedef int (__sys_shutdown_t)(int, int); +typedef int (__sys_socketpair_t)(int, int, int, int *); +typedef int (__sys_mkdir_t)(const char *, mode_t); +typedef int (__sys_rmdir_t)(const char *); +typedef int (__sys_utimes_t)(const char *, const struct timeval *); +typedef int (__sys_adjtime_t)(const struct timeval *, struct timeval *); +typedef int (__sys_setsid_t)(void); +typedef int (__sys_quotactl_t)(const char *, int, int, void *); +typedef int (__sys_nlm_syscall_t)(int, int, int, char **); +typedef int (__sys_nfssvc_t)(int, void *); +typedef int (__sys_lgetfh_t)(const char *, struct fhandle *); +typedef int (__sys_getfh_t)(const char *, struct fhandle *); +typedef int (__sys_sysarch_t)(int, char *); +typedef int (__sys_rtprio_t)(int, pid_t, struct rtprio *); +typedef int (__sys_semsys_t)(int, int, int, int, int); +typedef int (__sys_msgsys_t)(int, int, int, int, int, int); +typedef int (__sys_shmsys_t)(int, int, int, int); +typedef int (__sys_setfib_t)(int); +typedef int (__sys_ntp_adjtime_t)(struct timex *); +typedef int (__sys_setgid_t)(gid_t); +typedef int (__sys_setegid_t)(gid_t); +typedef int (__sys_seteuid_t)(uid_t); +typedef int (__sys_pathconf_t)(const char *, int); +typedef int (__sys_fpathconf_t)(int, int); +typedef int (__sys_getrlimit_t)(u_int, struct rlimit *); +typedef int (__sys_setrlimit_t)(u_int, struct rlimit *); +typedef int (__sys___sysctl_t)(const int *, u_int, void *, size_t *, const void *, size_t); +typedef int (__sys_mlock_t)(const void *, size_t); +typedef int (__sys_munlock_t)(const void *, size_t); +typedef int (__sys_undelete_t)(const char *); +typedef int (__sys_futimes_t)(int, const struct timeval *); +typedef int (__sys_getpgid_t)(pid_t); +typedef int (__sys_poll_t)(struct pollfd *, u_int, int); +typedef int (__sys_semget_t)(key_t, int, int); +typedef int (__sys_semop_t)(int, struct sembuf *, size_t); +typedef int (__sys_msgget_t)(key_t, int); +typedef int (__sys_msgsnd_t)(int, const void *, size_t, int); +typedef ssize_t (__sys_msgrcv_t)(int, void *, size_t, long, int); +typedef void * (__sys_shmat_t)(int, const void *, int); +typedef int (__sys_shmdt_t)(const void *); +typedef int (__sys_shmget_t)(key_t, size_t, int); +typedef int (__sys_clock_gettime_t)(clockid_t, struct timespec *); +typedef int (__sys_clock_settime_t)(clockid_t, const struct timespec *); +typedef int (__sys_clock_getres_t)(clockid_t, struct timespec *); +typedef int (__sys_ktimer_create_t)(clockid_t, struct sigevent *, int *); +typedef int (__sys_ktimer_delete_t)(int); +typedef int (__sys_ktimer_settime_t)(int, int, const struct itimerspec *, struct itimerspec *); +typedef int (__sys_ktimer_gettime_t)(int, struct itimerspec *); +typedef int (__sys_ktimer_getoverrun_t)(int); +typedef int (__sys_nanosleep_t)(const struct timespec *, struct timespec *); +typedef int (__sys_ffclock_getcounter_t)(ffcounter *); +typedef int (__sys_ffclock_setestimate_t)(struct ffclock_estimate *); +typedef int (__sys_ffclock_getestimate_t)(struct ffclock_estimate *); +typedef int (__sys_clock_nanosleep_t)(clockid_t, int, const struct timespec *, struct timespec *); +typedef int (__sys_clock_getcpuclockid2_t)(id_t, int, clockid_t *); +typedef int (__sys_ntp_gettime_t)(struct ntptimeval *); +typedef int (__sys_minherit_t)(void *, size_t, int); +typedef int (__sys_rfork_t)(int); +typedef int (__sys_issetugid_t)(void); +typedef int (__sys_lchown_t)(const char *, int, int); +typedef int (__sys_aio_read_t)(struct aiocb *); +typedef int (__sys_aio_write_t)(struct aiocb *); +typedef int (__sys_lio_listio_t)(int, struct aiocb * const *, int, struct sigevent *); +typedef int (__sys_lchmod_t)(const char *, mode_t); +typedef int (__sys_lutimes_t)(const char *, const struct timeval *); +typedef ssize_t (__sys_preadv_t)(int, struct iovec *, u_int, off_t); +typedef ssize_t (__sys_pwritev_t)(int, struct iovec *, u_int, off_t); +typedef int (__sys_fhopen_t)(const struct fhandle *, int); +typedef int (__sys_modnext_t)(int); +typedef int (__sys_modstat_t)(int, struct module_stat *); +typedef int (__sys_modfnext_t)(int); +typedef int (__sys_modfind_t)(const char *); +typedef int (__sys_kldload_t)(const char *); +typedef int (__sys_kldunload_t)(int); +typedef int (__sys_kldfind_t)(const char *); +typedef int (__sys_kldnext_t)(int); +typedef int (__sys_kldstat_t)(int, struct kld_file_stat *); +typedef int (__sys_kldfirstmod_t)(int); +typedef int (__sys_getsid_t)(pid_t); +typedef int (__sys_setresuid_t)(uid_t, uid_t, uid_t); +typedef int (__sys_setresgid_t)(gid_t, gid_t, gid_t); +typedef ssize_t (__sys_aio_return_t)(struct aiocb *); +typedef int (__sys_aio_suspend_t)(const struct aiocb * const *, int, const struct timespec *); +typedef int (__sys_aio_cancel_t)(int, struct aiocb *); +typedef int (__sys_aio_error_t)(struct aiocb *); +typedef int (__sys_mlockall_t)(int); +typedef int (__sys_munlockall_t)(void); +typedef int (__sys___getcwd_t)(char *, size_t); +typedef int (__sys_sched_setparam_t)(pid_t, const struct sched_param *); +typedef int (__sys_sched_getparam_t)(pid_t, struct sched_param *); +typedef int (__sys_sched_setscheduler_t)(pid_t, int, const struct sched_param *); +typedef int (__sys_sched_getscheduler_t)(pid_t); +typedef int (__sys_sched_yield_t)(void); +typedef int (__sys_sched_get_priority_max_t)(int); +typedef int (__sys_sched_get_priority_min_t)(int); +typedef int (__sys_sched_rr_get_interval_t)(pid_t, struct timespec *); +typedef int (__sys_utrace_t)(const void *, size_t); +typedef int (__sys_kldsym_t)(int, int, void *); +typedef int (__sys_jail_t)(struct jail *); +typedef int (__sys_nnpfs_syscall_t)(int, char *, int, void *, int); +typedef int (__sys_sigprocmask_t)(int, const sigset_t *, sigset_t *); +typedef int (__sys_sigsuspend_t)(const sigset_t *); +typedef int (__sys_sigpending_t)(sigset_t *); +typedef int (__sys_sigtimedwait_t)(const sigset_t *, struct __siginfo *, const struct timespec *); +typedef int (__sys_sigwaitinfo_t)(const sigset_t *, struct __siginfo *); +typedef int (__sys___acl_get_file_t)(const char *, __acl_type_t, struct acl *); +typedef int (__sys___acl_set_file_t)(const char *, __acl_type_t, struct acl *); +typedef int (__sys___acl_get_fd_t)(int, __acl_type_t, struct acl *); +typedef int (__sys___acl_set_fd_t)(int, __acl_type_t, struct acl *); +typedef int (__sys___acl_delete_file_t)(const char *, __acl_type_t); +typedef int (__sys___acl_delete_fd_t)(int, __acl_type_t); +typedef int (__sys___acl_aclcheck_file_t)(const char *, __acl_type_t, struct acl *); +typedef int (__sys___acl_aclcheck_fd_t)(int, __acl_type_t, struct acl *); +typedef int (__sys_extattrctl_t)(const char *, int, const char *, int, const char *); +typedef ssize_t (__sys_extattr_set_file_t)(const char *, int, const char *, void *, size_t); +typedef ssize_t (__sys_extattr_get_file_t)(const char *, int, const char *, void *, size_t); +typedef int (__sys_extattr_delete_file_t)(const char *, int, const char *); +typedef ssize_t (__sys_aio_waitcomplete_t)(struct aiocb **, struct timespec *); +typedef int (__sys_getresuid_t)(uid_t *, uid_t *, uid_t *); +typedef int (__sys_getresgid_t)(gid_t *, gid_t *, gid_t *); +typedef int (__sys_kqueue_t)(void); +typedef ssize_t (__sys_extattr_set_fd_t)(int, int, const char *, void *, size_t); +typedef ssize_t (__sys_extattr_get_fd_t)(int, int, const char *, void *, size_t); +typedef int (__sys_extattr_delete_fd_t)(int, int, const char *); +typedef int (__sys___setugid_t)(int); +typedef int (__sys_eaccess_t)(const char *, int); +typedef int (__sys_afs3_syscall_t)(long, long, long, long, long, long, long); +typedef int (__sys_nmount_t)(struct iovec *, unsigned int, int); +typedef int (__sys___mac_get_proc_t)(struct mac *); +typedef int (__sys___mac_set_proc_t)(struct mac *); +typedef int (__sys___mac_get_fd_t)(int, struct mac *); +typedef int (__sys___mac_get_file_t)(const char *, struct mac *); +typedef int (__sys___mac_set_fd_t)(int, struct mac *); +typedef int (__sys___mac_set_file_t)(const char *, struct mac *); +typedef int (__sys_kenv_t)(int, const char *, char *, int); +typedef int (__sys_lchflags_t)(const char *, u_long); +typedef int (__sys_uuidgen_t)(struct uuid *, int); +typedef int (__sys_sendfile_t)(int, int, off_t, size_t, struct sf_hdtr *, off_t *, int); +typedef int (__sys_mac_syscall_t)(const char *, int, void *); +typedef int (__sys_ksem_close_t)(semid_t); +typedef int (__sys_ksem_post_t)(semid_t); +typedef int (__sys_ksem_wait_t)(semid_t); +typedef int (__sys_ksem_trywait_t)(semid_t); +typedef int (__sys_ksem_init_t)(semid_t *, unsigned int); +typedef int (__sys_ksem_open_t)(semid_t *, const char *, int, mode_t, unsigned int); +typedef int (__sys_ksem_unlink_t)(const char *); +typedef int (__sys_ksem_getvalue_t)(semid_t, int *); +typedef int (__sys_ksem_destroy_t)(semid_t); +typedef int (__sys___mac_get_pid_t)(pid_t, struct mac *); +typedef int (__sys___mac_get_link_t)(const char *, struct mac *); +typedef int (__sys___mac_set_link_t)(const char *, struct mac *); +typedef ssize_t (__sys_extattr_set_link_t)(const char *, int, const char *, void *, size_t); +typedef ssize_t (__sys_extattr_get_link_t)(const char *, int, const char *, void *, size_t); +typedef int (__sys_extattr_delete_link_t)(const char *, int, const char *); +typedef int (__sys___mac_execve_t)(const char *, char **, char **, struct mac *); +typedef int (__sys_sigaction_t)(int, const struct sigaction *, struct sigaction *); +typedef int (__sys_sigreturn_t)(const struct __ucontext *); +typedef int (__sys_getcontext_t)(struct __ucontext *); +typedef int (__sys_setcontext_t)(const struct __ucontext *); +typedef int (__sys_swapcontext_t)(struct __ucontext *, const struct __ucontext *); +typedef int (__sys___acl_get_link_t)(const char *, __acl_type_t, struct acl *); +typedef int (__sys___acl_set_link_t)(const char *, __acl_type_t, struct acl *); +typedef int (__sys___acl_delete_link_t)(const char *, __acl_type_t); +typedef int (__sys___acl_aclcheck_link_t)(const char *, __acl_type_t, struct acl *); +typedef int (__sys_sigwait_t)(const sigset_t *, int *); +typedef int (__sys_thr_create_t)(ucontext_t *, long *, int); +typedef void (__sys_thr_exit_t)(long *); +typedef int (__sys_thr_self_t)(long *); +typedef int (__sys_thr_kill_t)(long, int); +typedef int (__sys_jail_attach_t)(int); +typedef ssize_t (__sys_extattr_list_fd_t)(int, int, void *, size_t); +typedef ssize_t (__sys_extattr_list_file_t)(const char *, int, void *, size_t); +typedef ssize_t (__sys_extattr_list_link_t)(const char *, int, void *, size_t); +typedef int (__sys_ksem_timedwait_t)(semid_t, const struct timespec *); +typedef int (__sys_thr_suspend_t)(const struct timespec *); +typedef int (__sys_thr_wake_t)(long); +typedef int (__sys_kldunloadf_t)(int, int); +typedef int (__sys_audit_t)(const void *, u_int); +typedef int (__sys_auditon_t)(int, void *, u_int); +typedef int (__sys_getauid_t)(uid_t *); +typedef int (__sys_setauid_t)(uid_t *); +typedef int (__sys_getaudit_t)(struct auditinfo *); +typedef int (__sys_setaudit_t)(struct auditinfo *); +typedef int (__sys_getaudit_addr_t)(struct auditinfo_addr *, u_int); +typedef int (__sys_setaudit_addr_t)(struct auditinfo_addr *, u_int); +typedef int (__sys_auditctl_t)(const char *); +typedef int (__sys__umtx_op_t)(void *, int, u_long, void *, void *); +typedef int (__sys_thr_new_t)(struct thr_param *, int); +typedef int (__sys_sigqueue_t)(pid_t, int, void *); +typedef int (__sys_kmq_open_t)(const char *, int, mode_t, const struct mq_attr *); +typedef int (__sys_kmq_setattr_t)(int, const struct mq_attr *, struct mq_attr *); +typedef int (__sys_kmq_timedreceive_t)(int, char *, size_t, unsigned *, const struct timespec *); +typedef int (__sys_kmq_timedsend_t)(int, const char *, size_t, unsigned, const struct timespec *); +typedef int (__sys_kmq_notify_t)(int, const struct sigevent *); +typedef int (__sys_kmq_unlink_t)(const char *); +typedef void (__sys_abort2_t)(const char *, int, void **); +typedef int (__sys_thr_set_name_t)(long, const char *); +typedef int (__sys_aio_fsync_t)(int, struct aiocb *); +typedef int (__sys_rtprio_thread_t)(int, lwpid_t, struct rtprio *); +typedef int (__sys_sctp_peeloff_t)(int, uint32_t); +typedef int (__sys_sctp_generic_sendmsg_t)(int, void *, int, const struct sockaddr *, __socklen_t, struct sctp_sndrcvinfo *, int); +typedef int (__sys_sctp_generic_sendmsg_iov_t)(int, struct iovec *, int, const struct sockaddr *, __socklen_t, struct sctp_sndrcvinfo *, int); +typedef int (__sys_sctp_generic_recvmsg_t)(int, struct iovec *, int, struct sockaddr *, __socklen_t *, struct sctp_sndrcvinfo *, int *); +typedef ssize_t (__sys_pread_t)(int, void *, size_t, off_t); +typedef ssize_t (__sys_pwrite_t)(int, const void *, size_t, off_t); +typedef void * (__sys_mmap_t)(void *, size_t, int, int, int, off_t); +typedef off_t (__sys_lseek_t)(int, off_t, int); +typedef int (__sys_truncate_t)(const char *, off_t); +typedef int (__sys_ftruncate_t)(int, off_t); +typedef int (__sys_thr_kill2_t)(pid_t, long, int); +typedef int (__sys_shm_unlink_t)(const char *); +typedef int (__sys_cpuset_t)(cpusetid_t *); +typedef int (__sys_cpuset_setid_t)(cpuwhich_t, id_t, cpusetid_t); +typedef int (__sys_cpuset_getid_t)(cpulevel_t, cpuwhich_t, id_t, cpusetid_t *); +typedef int (__sys_cpuset_getaffinity_t)(cpulevel_t, cpuwhich_t, id_t, size_t, cpuset_t *); +typedef int (__sys_cpuset_setaffinity_t)(cpulevel_t, cpuwhich_t, id_t, size_t, const cpuset_t *); +typedef int (__sys_faccessat_t)(int, const char *, int, int); +typedef int (__sys_fchmodat_t)(int, const char *, mode_t, int); +typedef int (__sys_fchownat_t)(int, const char *, uid_t, gid_t, int); +typedef int (__sys_fexecve_t)(int, char **, char **); +typedef int (__sys_futimesat_t)(int, const char *, const struct timeval *); +typedef int (__sys_linkat_t)(int, const char *, int, const char *, int); +typedef int (__sys_mkdirat_t)(int, const char *, mode_t); +typedef int (__sys_mkfifoat_t)(int, const char *, mode_t); +typedef int (__sys_openat_t)(int, const char *, int, mode_t); +typedef ssize_t (__sys_readlinkat_t)(int, const char *, char *, size_t); +typedef int (__sys_renameat_t)(int, const char *, int, const char *); +typedef int (__sys_symlinkat_t)(const char *, int, const char *); +typedef int (__sys_unlinkat_t)(int, const char *, int); +typedef int (__sys_posix_openpt_t)(int); +typedef int (__sys_jail_get_t)(struct iovec *, unsigned int, int); +typedef int (__sys_jail_set_t)(struct iovec *, unsigned int, int); +typedef int (__sys_jail_remove_t)(int); +typedef int (__sys___semctl_t)(int, int, int, union semun *); +typedef int (__sys_msgctl_t)(int, int, struct msqid_ds *); +typedef int (__sys_shmctl_t)(int, int, struct shmid_ds *); +typedef int (__sys_lpathconf_t)(const char *, int); +typedef int (__sys___cap_rights_get_t)(int, int, cap_rights_t *); +typedef int (__sys_cap_enter_t)(void); +typedef int (__sys_cap_getmode_t)(u_int *); +typedef int (__sys_pdfork_t)(int *, int); +typedef int (__sys_pdkill_t)(int, int); +typedef int (__sys_pdgetpid_t)(int, pid_t *); +typedef int (__sys_pselect_t)(int, fd_set *, fd_set *, fd_set *, const struct timespec *, const sigset_t *); +typedef int (__sys_getloginclass_t)(char *, size_t); +typedef int (__sys_setloginclass_t)(const char *); +typedef int (__sys_rctl_get_racct_t)(const void *, size_t, void *, size_t); +typedef int (__sys_rctl_get_rules_t)(const void *, size_t, void *, size_t); +typedef int (__sys_rctl_get_limits_t)(const void *, size_t, void *, size_t); +typedef int (__sys_rctl_add_rule_t)(const void *, size_t, void *, size_t); +typedef int (__sys_rctl_remove_rule_t)(const void *, size_t, void *, size_t); +typedef int (__sys_posix_fallocate_t)(int, off_t, off_t); +typedef int (__sys_posix_fadvise_t)(int, off_t, off_t, int); +typedef int (__sys_wait6_t)(idtype_t, id_t, int *, int, struct __wrusage *, struct __siginfo *); +typedef int (__sys_cap_rights_limit_t)(int, cap_rights_t *); +typedef int (__sys_cap_ioctls_limit_t)(int, const u_long *, size_t); +typedef ssize_t (__sys_cap_ioctls_get_t)(int, u_long *, size_t); +typedef int (__sys_cap_fcntls_limit_t)(int, uint32_t); +typedef int (__sys_cap_fcntls_get_t)(int, uint32_t *); +typedef int (__sys_bindat_t)(int, int, const struct sockaddr *, __socklen_t); +typedef int (__sys_connectat_t)(int, int, const struct sockaddr *, __socklen_t); +typedef int (__sys_chflagsat_t)(int, const char *, u_long, int); +typedef int (__sys_accept4_t)(int, struct sockaddr *, __socklen_t *, int); +typedef int (__sys_pipe2_t)(int *, int); +typedef int (__sys_aio_mlock_t)(struct aiocb *); +typedef int (__sys_procctl_t)(idtype_t, id_t, int, void *); +typedef int (__sys_ppoll_t)(struct pollfd *, u_int, const struct timespec *, const sigset_t *); +typedef int (__sys_futimens_t)(int, const struct timespec *); +typedef int (__sys_utimensat_t)(int, const char *, const struct timespec *, int); +typedef int (__sys_fdatasync_t)(int); +typedef int (__sys_fstat_t)(int, struct stat *); +typedef int (__sys_fstatat_t)(int, const char *, struct stat *, int); +typedef int (__sys_fhstat_t)(const struct fhandle *, struct stat *); +typedef ssize_t (__sys_getdirentries_t)(int, char *, size_t, off_t *); +typedef int (__sys_statfs_t)(const char *, struct statfs *); +typedef int (__sys_fstatfs_t)(int, struct statfs *); +typedef int (__sys_getfsstat_t)(struct statfs *, long, int); +typedef int (__sys_fhstatfs_t)(const struct fhandle *, struct statfs *); +typedef int (__sys_mknodat_t)(int, const char *, mode_t, dev_t); +typedef int (__sys_kevent_t)(int, const struct kevent *, int, struct kevent *, int, const struct timespec *); +typedef int (__sys_cpuset_getdomain_t)(cpulevel_t, cpuwhich_t, id_t, size_t, domainset_t *, int *); +typedef int (__sys_cpuset_setdomain_t)(cpulevel_t, cpuwhich_t, id_t, size_t, domainset_t *, int); +typedef int (__sys_getrandom_t)(void *, size_t, unsigned int); +typedef int (__sys_getfhat_t)(int, char *, struct fhandle *, int); +typedef int (__sys_fhlink_t)(struct fhandle *, const char *); +typedef int (__sys_fhlinkat_t)(struct fhandle *, int, const char *); +typedef int (__sys_fhreadlink_t)(struct fhandle *, char *, size_t); +typedef int (__sys_funlinkat_t)(int, const char *, int, int); +typedef ssize_t (__sys_copy_file_range_t)(int, off_t *, int, off_t *, size_t, unsigned int); +typedef int (__sys___sysctlbyname_t)(const char *, size_t, void *, size_t *, void *, size_t); +typedef int (__sys_shm_open2_t)(const char *, int, mode_t, int, const char *); +typedef int (__sys_shm_rename_t)(const char *, const char *, int); +typedef int (__sys_sigfastblock_t)(int, void *); +typedef int (__sys___realpathat_t)(int, const char *, char *, size_t, int); +typedef int (__sys_close_range_t)(u_int, u_int, int); +typedef int (__sys_rpctls_syscall_t)(uint64_t); +typedef int (__sys___specialfd_t)(int, const void *, size_t); +typedef int (__sys_aio_writev_t)(struct aiocb *); +typedef int (__sys_aio_readv_t)(struct aiocb *); +typedef int (__sys_fspacectl_t)(int, int, const struct spacectl_range *, int, struct spacectl_range *); +typedef int (__sys_sched_getcpu_t)(void); +typedef int (__sys_swapoff_t)(const char *, u_int); +typedef int (__sys_kqueuex_t)(u_int); +typedef int (__sys_membarrier_t)(int, unsigned, int); +typedef int (__sys_timerfd_create_t)(int, int); +typedef int (__sys_timerfd_gettime_t)(int, struct itimerspec *); +typedef int (__sys_timerfd_settime_t)(int, int, const struct itimerspec *, struct itimerspec *); +typedef int (__sys_kcmp_t)(pid_t, pid_t, int, uintptr_t, uintptr_t); +typedef int (__sys_getrlimitusage_t)(u_int, int, rlim_t *); +typedef int (__sys_fchroot_t)(int); +typedef int (__sys_setcred_t)(u_int, const struct setcred *, size_t); +typedef int (__sys_exterrctl_t)(u_int, u_int, void *); +typedef int (__sys_inotify_add_watch_at_t)(int, int, const char *, uint32_t); +typedef int (__sys_inotify_rm_watch_t)(int, int); + +void __sys_exit(int rval); +int __sys_fork(void); +ssize_t __sys_read(int fd, void * buf, size_t nbyte); +ssize_t __sys_write(int fd, const void * buf, size_t nbyte); +int __sys_open(const char * path, int flags, mode_t mode); +int __sys_close(int fd); +int __sys_wait4(int pid, int * status, int options, struct rusage * rusage); +int __sys_link(const char * path, const char * link); +int __sys_unlink(const char * path); +int __sys_chdir(const char * path); +int __sys_fchdir(int fd); +int __sys_chmod(const char * path, mode_t mode); +int __sys_chown(const char * path, int uid, int gid); +void * __sys_break(char * nsize); +pid_t __sys_getpid(void); +int __sys_mount(const char * type, const char * path, int flags, void * data); +int __sys_unmount(const char * path, int flags); +int __sys_setuid(uid_t uid); +uid_t __sys_getuid(void); +uid_t __sys_geteuid(void); +int __sys_ptrace(int req, pid_t pid, caddr_t addr, int data); +ssize_t __sys_recvmsg(int s, struct msghdr * msg, int flags); +ssize_t __sys_sendmsg(int s, const struct msghdr * msg, int flags); +ssize_t __sys_recvfrom(int s, void * buf, size_t len, int flags, struct sockaddr * from, __socklen_t * fromlenaddr); +int __sys_accept(int s, struct sockaddr * name, __socklen_t * anamelen); +int __sys_getpeername(int fdes, struct sockaddr * asa, __socklen_t * alen); +int __sys_getsockname(int fdes, struct sockaddr * asa, __socklen_t * alen); +int __sys_access(const char * path, int amode); +int __sys_chflags(const char * path, u_long flags); +int __sys_fchflags(int fd, u_long flags); +int __sys_sync(void); +int __sys_kill(int pid, int signum); +pid_t __sys_getppid(void); +int __sys_dup(u_int fd); +gid_t __sys_getegid(void); +int __sys_profil(char * samples, size_t size, size_t offset, u_int scale); +int __sys_ktrace(const char * fname, int ops, int facs, int pid); +gid_t __sys_getgid(void); +int __sys_getlogin(char * namebuf, u_int namelen); +int __sys_setlogin(const char * namebuf); +int __sys_acct(const char * path); +int __sys_sigaltstack(const struct sigaltstack * ss, struct sigaltstack * oss); +int __sys_ioctl(int fd, u_long com, char * data); +int __sys_reboot(int opt); +int __sys_revoke(const char * path); +int __sys_symlink(const char * path, const char * link); +ssize_t __sys_readlink(const char * path, char * buf, size_t count); +int __sys_execve(const char * fname, char ** argv, char ** envv); +mode_t __sys_umask(mode_t newmask); +int __sys_chroot(const char * path); +int __sys_msync(void * addr, size_t len, int flags); +int __sys_vfork(void); +int __sys_munmap(void * addr, size_t len); +int __sys_mprotect(void * addr, size_t len, int prot); +int __sys_madvise(void * addr, size_t len, int behav); +int __sys_mincore(const void * addr, size_t len, char * vec); +int __sys_getgroups(int gidsetsize, gid_t * gidset); +int __sys_setgroups(int gidsetsize, const gid_t * gidset); +int __sys_getpgrp(void); +int __sys_setpgid(int pid, int pgid); +int __sys_setitimer(int which, const struct itimerval * itv, struct itimerval * oitv); +int __sys_swapon(const char * name); +int __sys_getitimer(int which, struct itimerval * itv); +int __sys_getdtablesize(void); +int __sys_dup2(u_int from, u_int to); +int __sys_fcntl(int fd, int cmd, intptr_t arg); +int __sys_select(int nd, fd_set * in, fd_set * ou, fd_set * ex, struct timeval * tv); +int __sys_fsync(int fd); +int __sys_setpriority(int which, int who, int prio); +int __sys_socket(int domain, int type, int protocol); +int __sys_connect(int s, const struct sockaddr * name, __socklen_t namelen); +int __sys_getpriority(int which, int who); +int __sys_bind(int s, const struct sockaddr * name, __socklen_t namelen); +int __sys_setsockopt(int s, int level, int name, const void * val, __socklen_t valsize); +int __sys_listen(int s, int backlog); +int __sys_gettimeofday(struct timeval * tp, struct timezone * tzp); +int __sys_getrusage(int who, struct rusage * rusage); +int __sys_getsockopt(int s, int level, int name, void * val, __socklen_t * avalsize); +ssize_t __sys_readv(int fd, const struct iovec * iovp, u_int iovcnt); +ssize_t __sys_writev(int fd, const struct iovec * iovp, u_int iovcnt); +int __sys_settimeofday(const struct timeval * tv, const struct timezone * tzp); +int __sys_fchown(int fd, int uid, int gid); +int __sys_fchmod(int fd, mode_t mode); +int __sys_setreuid(int ruid, int euid); +int __sys_setregid(int rgid, int egid); +int __sys_rename(const char * from, const char * to); +int __sys_flock(int fd, int how); +int __sys_mkfifo(const char * path, mode_t mode); +ssize_t __sys_sendto(int s, const void * buf, size_t len, int flags, const struct sockaddr * to, __socklen_t tolen); +int __sys_shutdown(int s, int how); +int __sys_socketpair(int domain, int type, int protocol, int * rsv); +int __sys_mkdir(const char * path, mode_t mode); +int __sys_rmdir(const char * path); +int __sys_utimes(const char * path, const struct timeval * tptr); +int __sys_adjtime(const struct timeval * delta, struct timeval * olddelta); +int __sys_setsid(void); +int __sys_quotactl(const char * path, int cmd, int uid, void * arg); +int __sys_nlm_syscall(int debug_level, int grace_period, int addr_count, char ** addrs); +int __sys_nfssvc(int flag, void * argp); +int __sys_lgetfh(const char * fname, struct fhandle * fhp); +int __sys_getfh(const char * fname, struct fhandle * fhp); +int __sys_sysarch(int op, char * parms); +int __sys_rtprio(int function, pid_t pid, struct rtprio * rtp); +int __sys_semsys(int which, int a2, int a3, int a4, int a5); +int __sys_msgsys(int which, int a2, int a3, int a4, int a5, int a6); +int __sys_shmsys(int which, int a2, int a3, int a4); +int __sys_setfib(int fibnum); +int __sys_ntp_adjtime(struct timex * tp); +int __sys_setgid(gid_t gid); +int __sys_setegid(gid_t egid); +int __sys_seteuid(uid_t euid); +int __sys_pathconf(const char * path, int name); +int __sys_fpathconf(int fd, int name); +int __sys_getrlimit(u_int which, struct rlimit * rlp); +int __sys_setrlimit(u_int which, struct rlimit * rlp); +int __sys___sysctl(const int * name, u_int namelen, void * old, size_t * oldlenp, const void * new, size_t newlen); +int __sys_mlock(const void * addr, size_t len); +int __sys_munlock(const void * addr, size_t len); +int __sys_undelete(const char * path); +int __sys_futimes(int fd, const struct timeval * tptr); +int __sys_getpgid(pid_t pid); +int __sys_poll(struct pollfd * fds, u_int nfds, int timeout); +int __sys_semget(key_t key, int nsems, int semflg); +int __sys_semop(int semid, struct sembuf * sops, size_t nsops); +int __sys_msgget(key_t key, int msgflg); +int __sys_msgsnd(int msqid, const void * msgp, size_t msgsz, int msgflg); +ssize_t __sys_msgrcv(int msqid, void * msgp, size_t msgsz, long msgtyp, int msgflg); +void * __sys_shmat(int shmid, const void * shmaddr, int shmflg); +int __sys_shmdt(const void * shmaddr); +int __sys_shmget(key_t key, size_t size, int shmflg); +int __sys_clock_gettime(clockid_t clock_id, struct timespec * tp); +int __sys_clock_settime(clockid_t clock_id, const struct timespec * tp); +int __sys_clock_getres(clockid_t clock_id, struct timespec * tp); +int __sys_ktimer_create(clockid_t clock_id, struct sigevent * evp, int * timerid); +int __sys_ktimer_delete(int timerid); +int __sys_ktimer_settime(int timerid, int flags, const struct itimerspec * value, struct itimerspec * ovalue); +int __sys_ktimer_gettime(int timerid, struct itimerspec * value); +int __sys_ktimer_getoverrun(int timerid); +int __sys_nanosleep(const struct timespec * rqtp, struct timespec * rmtp); +int __sys_ffclock_getcounter(ffcounter * ffcount); +int __sys_ffclock_setestimate(struct ffclock_estimate * cest); +int __sys_ffclock_getestimate(struct ffclock_estimate * cest); +int __sys_clock_nanosleep(clockid_t clock_id, int flags, const struct timespec * rqtp, struct timespec * rmtp); +int __sys_clock_getcpuclockid2(id_t id, int which, clockid_t * clock_id); +int __sys_ntp_gettime(struct ntptimeval * ntvp); +int __sys_minherit(void * addr, size_t len, int inherit); +int __sys_rfork(int flags); +int __sys_issetugid(void); +int __sys_lchown(const char * path, int uid, int gid); +int __sys_aio_read(struct aiocb * aiocbp); +int __sys_aio_write(struct aiocb * aiocbp); +int __sys_lio_listio(int mode, struct aiocb * const * acb_list, int nent, struct sigevent * sig); +int __sys_lchmod(const char * path, mode_t mode); +int __sys_lutimes(const char * path, const struct timeval * tptr); +ssize_t __sys_preadv(int fd, struct iovec * iovp, u_int iovcnt, off_t offset); +ssize_t __sys_pwritev(int fd, struct iovec * iovp, u_int iovcnt, off_t offset); +int __sys_fhopen(const struct fhandle * u_fhp, int flags); +int __sys_modnext(int modid); +int __sys_modstat(int modid, struct module_stat * stat); +int __sys_modfnext(int modid); +int __sys_modfind(const char * name); +int __sys_kldload(const char * file); +int __sys_kldunload(int fileid); +int __sys_kldfind(const char * file); +int __sys_kldnext(int fileid); +int __sys_kldstat(int fileid, struct kld_file_stat * stat); +int __sys_kldfirstmod(int fileid); +int __sys_getsid(pid_t pid); +int __sys_setresuid(uid_t ruid, uid_t euid, uid_t suid); +int __sys_setresgid(gid_t rgid, gid_t egid, gid_t sgid); +ssize_t __sys_aio_return(struct aiocb * aiocbp); +int __sys_aio_suspend(const struct aiocb * const * aiocbp, int nent, const struct timespec * timeout); +int __sys_aio_cancel(int fd, struct aiocb * aiocbp); +int __sys_aio_error(struct aiocb * aiocbp); +int __sys_mlockall(int how); +int __sys_munlockall(void); +int __sys___getcwd(char * buf, size_t buflen); +int __sys_sched_setparam(pid_t pid, const struct sched_param * param); +int __sys_sched_getparam(pid_t pid, struct sched_param * param); +int __sys_sched_setscheduler(pid_t pid, int policy, const struct sched_param * param); +int __sys_sched_getscheduler(pid_t pid); +int __sys_sched_yield(void); +int __sys_sched_get_priority_max(int policy); +int __sys_sched_get_priority_min(int policy); +int __sys_sched_rr_get_interval(pid_t pid, struct timespec * interval); +int __sys_utrace(const void * addr, size_t len); +int __sys_kldsym(int fileid, int cmd, void * data); +int __sys_jail(struct jail * jail); +int __sys_nnpfs_syscall(int operation, char * a_pathP, int a_opcode, void * a_paramsP, int a_followSymlinks); +int __sys_sigprocmask(int how, const sigset_t * set, sigset_t * oset); +int __sys_sigsuspend(const sigset_t * sigmask); +int __sys_sigpending(sigset_t * set); +int __sys_sigtimedwait(const sigset_t * set, struct __siginfo * info, const struct timespec * timeout); +int __sys_sigwaitinfo(const sigset_t * set, struct __siginfo * info); +int __sys___acl_get_file(const char * path, __acl_type_t type, struct acl * aclp); +int __sys___acl_set_file(const char * path, __acl_type_t type, struct acl * aclp); +int __sys___acl_get_fd(int filedes, __acl_type_t type, struct acl * aclp); +int __sys___acl_set_fd(int filedes, __acl_type_t type, struct acl * aclp); +int __sys___acl_delete_file(const char * path, __acl_type_t type); +int __sys___acl_delete_fd(int filedes, __acl_type_t type); +int __sys___acl_aclcheck_file(const char * path, __acl_type_t type, struct acl * aclp); +int __sys___acl_aclcheck_fd(int filedes, __acl_type_t type, struct acl * aclp); +int __sys_extattrctl(const char * path, int cmd, const char * filename, int attrnamespace, const char * attrname); +ssize_t __sys_extattr_set_file(const char * path, int attrnamespace, const char * attrname, void * data, size_t nbytes); +ssize_t __sys_extattr_get_file(const char * path, int attrnamespace, const char * attrname, void * data, size_t nbytes); +int __sys_extattr_delete_file(const char * path, int attrnamespace, const char * attrname); +ssize_t __sys_aio_waitcomplete(struct aiocb ** aiocbp, struct timespec * timeout); +int __sys_getresuid(uid_t * ruid, uid_t * euid, uid_t * suid); +int __sys_getresgid(gid_t * rgid, gid_t * egid, gid_t * sgid); +int __sys_kqueue(void); +ssize_t __sys_extattr_set_fd(int fd, int attrnamespace, const char * attrname, void * data, size_t nbytes); +ssize_t __sys_extattr_get_fd(int fd, int attrnamespace, const char * attrname, void * data, size_t nbytes); +int __sys_extattr_delete_fd(int fd, int attrnamespace, const char * attrname); +int __sys___setugid(int flag); +int __sys_eaccess(const char * path, int amode); +int __sys_afs3_syscall(long syscall, long parm1, long parm2, long parm3, long parm4, long parm5, long parm6); +int __sys_nmount(struct iovec * iovp, unsigned int iovcnt, int flags); +int __sys___mac_get_proc(struct mac * mac_p); +int __sys___mac_set_proc(struct mac * mac_p); +int __sys___mac_get_fd(int fd, struct mac * mac_p); +int __sys___mac_get_file(const char * path_p, struct mac * mac_p); +int __sys___mac_set_fd(int fd, struct mac * mac_p); +int __sys___mac_set_file(const char * path_p, struct mac * mac_p); +int __sys_kenv(int what, const char * name, char * value, int len); +int __sys_lchflags(const char * path, u_long flags); +int __sys_uuidgen(struct uuid * store, int count); +int __sys_sendfile(int fd, int s, off_t offset, size_t nbytes, struct sf_hdtr * hdtr, off_t * sbytes, int flags); +int __sys_mac_syscall(const char * policy, int call, void * arg); +int __sys_ksem_close(semid_t id); +int __sys_ksem_post(semid_t id); +int __sys_ksem_wait(semid_t id); +int __sys_ksem_trywait(semid_t id); +int __sys_ksem_init(semid_t * idp, unsigned int value); +int __sys_ksem_open(semid_t * idp, const char * name, int oflag, mode_t mode, unsigned int value); +int __sys_ksem_unlink(const char * name); +int __sys_ksem_getvalue(semid_t id, int * val); +int __sys_ksem_destroy(semid_t id); +int __sys___mac_get_pid(pid_t pid, struct mac * mac_p); +int __sys___mac_get_link(const char * path_p, struct mac * mac_p); +int __sys___mac_set_link(const char * path_p, struct mac * mac_p); +ssize_t __sys_extattr_set_link(const char * path, int attrnamespace, const char * attrname, void * data, size_t nbytes); +ssize_t __sys_extattr_get_link(const char * path, int attrnamespace, const char * attrname, void * data, size_t nbytes); +int __sys_extattr_delete_link(const char * path, int attrnamespace, const char * attrname); +int __sys___mac_execve(const char * fname, char ** argv, char ** envv, struct mac * mac_p); +int __sys_sigaction(int sig, const struct sigaction * act, struct sigaction * oact); +int __sys_sigreturn(const struct __ucontext * sigcntxp); +int __sys_getcontext(struct __ucontext * ucp); +int __sys_setcontext(const struct __ucontext * ucp); +int __sys_swapcontext(struct __ucontext * oucp, const struct __ucontext * ucp); +int __sys___acl_get_link(const char * path, __acl_type_t type, struct acl * aclp); +int __sys___acl_set_link(const char * path, __acl_type_t type, struct acl * aclp); +int __sys___acl_delete_link(const char * path, __acl_type_t type); +int __sys___acl_aclcheck_link(const char * path, __acl_type_t type, struct acl * aclp); +int __sys_sigwait(const sigset_t * set, int * sig); +int __sys_thr_create(ucontext_t * ctx, long * id, int flags); +void __sys_thr_exit(long * state); +int __sys_thr_self(long * id); +int __sys_thr_kill(long id, int sig); +int __sys_jail_attach(int jid); +ssize_t __sys_extattr_list_fd(int fd, int attrnamespace, void * data, size_t nbytes); +ssize_t __sys_extattr_list_file(const char * path, int attrnamespace, void * data, size_t nbytes); +ssize_t __sys_extattr_list_link(const char * path, int attrnamespace, void * data, size_t nbytes); +int __sys_ksem_timedwait(semid_t id, const struct timespec * abstime); +int __sys_thr_suspend(const struct timespec * timeout); +int __sys_thr_wake(long id); +int __sys_kldunloadf(int fileid, int flags); +int __sys_audit(const void * record, u_int length); +int __sys_auditon(int cmd, void * data, u_int length); +int __sys_getauid(uid_t * auid); +int __sys_setauid(uid_t * auid); +int __sys_getaudit(struct auditinfo * auditinfo); +int __sys_setaudit(struct auditinfo * auditinfo); +int __sys_getaudit_addr(struct auditinfo_addr * auditinfo_addr, u_int length); +int __sys_setaudit_addr(struct auditinfo_addr * auditinfo_addr, u_int length); +int __sys_auditctl(const char * path); +int __sys__umtx_op(void * obj, int op, u_long val, void * uaddr1, void * uaddr2); +int __sys_thr_new(struct thr_param * param, int param_size); +int __sys_sigqueue(pid_t pid, int signum, void * value); +int __sys_kmq_open(const char * path, int flags, mode_t mode, const struct mq_attr * attr); +int __sys_kmq_setattr(int mqd, const struct mq_attr * attr, struct mq_attr * oattr); +int __sys_kmq_timedreceive(int mqd, char * msg_ptr, size_t msg_len, unsigned * msg_prio, const struct timespec * abs_timeout); +int __sys_kmq_timedsend(int mqd, const char * msg_ptr, size_t msg_len, unsigned msg_prio, const struct timespec * abs_timeout); +int __sys_kmq_notify(int mqd, const struct sigevent * sigev); +int __sys_kmq_unlink(const char * path); +void __sys_abort2(const char * why, int nargs, void ** args); +int __sys_thr_set_name(long id, const char * name); +int __sys_aio_fsync(int op, struct aiocb * aiocbp); +int __sys_rtprio_thread(int function, lwpid_t lwpid, struct rtprio * rtp); +int __sys_sctp_peeloff(int sd, uint32_t name); +int __sys_sctp_generic_sendmsg(int sd, void * msg, int mlen, const struct sockaddr * to, __socklen_t tolen, struct sctp_sndrcvinfo * sinfo, int flags); +int __sys_sctp_generic_sendmsg_iov(int sd, struct iovec * iov, int iovlen, const struct sockaddr * to, __socklen_t tolen, struct sctp_sndrcvinfo * sinfo, int flags); +int __sys_sctp_generic_recvmsg(int sd, struct iovec * iov, int iovlen, struct sockaddr * from, __socklen_t * fromlenaddr, struct sctp_sndrcvinfo * sinfo, int * msg_flags); +ssize_t __sys_pread(int fd, void * buf, size_t nbyte, off_t offset); +ssize_t __sys_pwrite(int fd, const void * buf, size_t nbyte, off_t offset); +void * __sys_mmap(void * addr, size_t len, int prot, int flags, int fd, off_t pos); +off_t __sys_lseek(int fd, off_t offset, int whence); +int __sys_truncate(const char * path, off_t length); +int __sys_ftruncate(int fd, off_t length); +int __sys_thr_kill2(pid_t pid, long id, int sig); +int __sys_shm_unlink(const char * path); +int __sys_cpuset(cpusetid_t * setid); +int __sys_cpuset_setid(cpuwhich_t which, id_t id, cpusetid_t setid); +int __sys_cpuset_getid(cpulevel_t level, cpuwhich_t which, id_t id, cpusetid_t * setid); +int __sys_cpuset_getaffinity(cpulevel_t level, cpuwhich_t which, id_t id, size_t cpusetsize, cpuset_t * mask); +int __sys_cpuset_setaffinity(cpulevel_t level, cpuwhich_t which, id_t id, size_t cpusetsize, const cpuset_t * mask); +int __sys_faccessat(int fd, const char * path, int amode, int flag); +int __sys_fchmodat(int fd, const char * path, mode_t mode, int flag); +int __sys_fchownat(int fd, const char * path, uid_t uid, gid_t gid, int flag); +int __sys_fexecve(int fd, char ** argv, char ** envv); +int __sys_futimesat(int fd, const char * path, const struct timeval * times); +int __sys_linkat(int fd1, const char * path1, int fd2, const char * path2, int flag); +int __sys_mkdirat(int fd, const char * path, mode_t mode); +int __sys_mkfifoat(int fd, const char * path, mode_t mode); +int __sys_openat(int fd, const char * path, int flag, mode_t mode); +ssize_t __sys_readlinkat(int fd, const char * path, char * buf, size_t bufsize); +int __sys_renameat(int oldfd, const char * old, int newfd, const char * new); +int __sys_symlinkat(const char * path1, int fd, const char * path2); +int __sys_unlinkat(int fd, const char * path, int flag); +int __sys_posix_openpt(int flags); +int __sys_jail_get(struct iovec * iovp, unsigned int iovcnt, int flags); +int __sys_jail_set(struct iovec * iovp, unsigned int iovcnt, int flags); +int __sys_jail_remove(int jid); +int __sys___semctl(int semid, int semnum, int cmd, union semun * arg); +int __sys_msgctl(int msqid, int cmd, struct msqid_ds * buf); +int __sys_shmctl(int shmid, int cmd, struct shmid_ds * buf); +int __sys_lpathconf(const char * path, int name); +int __sys___cap_rights_get(int version, int fd, cap_rights_t * rightsp); +int __sys_cap_enter(void); +int __sys_cap_getmode(u_int * modep); +int __sys_pdfork(int * fdp, int flags); +int __sys_pdkill(int fd, int signum); +int __sys_pdgetpid(int fd, pid_t * pidp); +int __sys_pselect(int nd, fd_set * in, fd_set * ou, fd_set * ex, const struct timespec * ts, const sigset_t * sm); +int __sys_getloginclass(char * namebuf, size_t namelen); +int __sys_setloginclass(const char * namebuf); +int __sys_rctl_get_racct(const void * inbufp, size_t inbuflen, void * outbufp, size_t outbuflen); +int __sys_rctl_get_rules(const void * inbufp, size_t inbuflen, void * outbufp, size_t outbuflen); +int __sys_rctl_get_limits(const void * inbufp, size_t inbuflen, void * outbufp, size_t outbuflen); +int __sys_rctl_add_rule(const void * inbufp, size_t inbuflen, void * outbufp, size_t outbuflen); +int __sys_rctl_remove_rule(const void * inbufp, size_t inbuflen, void * outbufp, size_t outbuflen); +int __sys_posix_fallocate(int fd, off_t offset, off_t len); +int __sys_posix_fadvise(int fd, off_t offset, off_t len, int advice); +int __sys_wait6(idtype_t idtype, id_t id, int * status, int options, struct __wrusage * wrusage, struct __siginfo * info); +int __sys_cap_rights_limit(int fd, cap_rights_t * rightsp); +int __sys_cap_ioctls_limit(int fd, const u_long * cmds, size_t ncmds); +ssize_t __sys_cap_ioctls_get(int fd, u_long * cmds, size_t maxcmds); +int __sys_cap_fcntls_limit(int fd, uint32_t fcntlrights); +int __sys_cap_fcntls_get(int fd, uint32_t * fcntlrightsp); +int __sys_bindat(int fd, int s, const struct sockaddr * name, __socklen_t namelen); +int __sys_connectat(int fd, int s, const struct sockaddr * name, __socklen_t namelen); +int __sys_chflagsat(int fd, const char * path, u_long flags, int atflag); +int __sys_accept4(int s, struct sockaddr * name, __socklen_t * anamelen, int flags); +int __sys_pipe2(int * fildes, int flags); +int __sys_aio_mlock(struct aiocb * aiocbp); +int __sys_procctl(idtype_t idtype, id_t id, int com, void * data); +int __sys_ppoll(struct pollfd * fds, u_int nfds, const struct timespec * ts, const sigset_t * set); +int __sys_futimens(int fd, const struct timespec * times); +int __sys_utimensat(int fd, const char * path, const struct timespec * times, int flag); +int __sys_fdatasync(int fd); +int __sys_fstat(int fd, struct stat * sb); +int __sys_fstatat(int fd, const char * path, struct stat * buf, int flag); +int __sys_fhstat(const struct fhandle * u_fhp, struct stat * sb); +ssize_t __sys_getdirentries(int fd, char * buf, size_t count, off_t * basep); +int __sys_statfs(const char * path, struct statfs * buf); +int __sys_fstatfs(int fd, struct statfs * buf); +int __sys_getfsstat(struct statfs * buf, long bufsize, int mode); +int __sys_fhstatfs(const struct fhandle * u_fhp, struct statfs * buf); +int __sys_mknodat(int fd, const char * path, mode_t mode, dev_t dev); +int __sys_kevent(int fd, const struct kevent * changelist, int nchanges, struct kevent * eventlist, int nevents, const struct timespec * timeout); +int __sys_cpuset_getdomain(cpulevel_t level, cpuwhich_t which, id_t id, size_t domainsetsize, domainset_t * mask, int * policy); +int __sys_cpuset_setdomain(cpulevel_t level, cpuwhich_t which, id_t id, size_t domainsetsize, domainset_t * mask, int policy); +int __sys_getrandom(void * buf, size_t buflen, unsigned int flags); +int __sys_getfhat(int fd, char * path, struct fhandle * fhp, int flags); +int __sys_fhlink(struct fhandle * fhp, const char * to); +int __sys_fhlinkat(struct fhandle * fhp, int tofd, const char * to); +int __sys_fhreadlink(struct fhandle * fhp, char * buf, size_t bufsize); +int __sys_funlinkat(int dfd, const char * path, int fd, int flag); +ssize_t __sys_copy_file_range(int infd, off_t * inoffp, int outfd, off_t * outoffp, size_t len, unsigned int flags); +int __sys___sysctlbyname(const char * name, size_t namelen, void * old, size_t * oldlenp, void * new, size_t newlen); +int __sys_shm_open2(const char * path, int flags, mode_t mode, int shmflags, const char * name); +int __sys_shm_rename(const char * path_from, const char * path_to, int flags); +int __sys_sigfastblock(int cmd, void * ptr); +int __sys___realpathat(int fd, const char * path, char * buf, size_t size, int flags); +int __sys_close_range(u_int lowfd, u_int highfd, int flags); +int __sys_rpctls_syscall(uint64_t socookie); +int __sys___specialfd(int type, const void * req, size_t len); +int __sys_aio_writev(struct aiocb * aiocbp); +int __sys_aio_readv(struct aiocb * aiocbp); +int __sys_fspacectl(int fd, int cmd, const struct spacectl_range * rqsr, int flags, struct spacectl_range * rmsr); +int __sys_sched_getcpu(void); +int __sys_swapoff(const char * name, u_int flags); +int __sys_kqueuex(u_int flags); +int __sys_membarrier(int cmd, unsigned flags, int cpu_id); +int __sys_timerfd_create(int clockid, int flags); +int __sys_timerfd_gettime(int fd, struct itimerspec * curr_value); +int __sys_timerfd_settime(int fd, int flags, const struct itimerspec * new_value, struct itimerspec * old_value); +int __sys_kcmp(pid_t pid1, pid_t pid2, int type, uintptr_t idx1, uintptr_t idx2); +int __sys_getrlimitusage(u_int which, int flags, rlim_t * res); +int __sys_fchroot(int fd); +int __sys_setcred(u_int flags, const struct setcred * wcred, size_t size); +int __sys_exterrctl(u_int op, u_int flags, void * ptr); +int __sys_inotify_add_watch_at(int fd, int dfd, const char * path, uint32_t mask); +int __sys_inotify_rm_watch(int fd, int wd); +__END_DECLS + +#endif /* __LIBSYS_H_ */ diff --git a/lib/libsys/_umtx_op.2 b/lib/libsys/_umtx_op.2 new file mode 100644 index 000000000000..c590f8e8e0c8 --- /dev/null +++ b/lib/libsys/_umtx_op.2 @@ -0,0 +1,1541 @@ +.\" Copyright (c) 2016 The FreeBSD Foundation +.\" +.\" This documentation was written by +.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" 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 AUTHORS 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 AUTHORS 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. +.\" +.Dd November 23, 2020 +.Dt _UMTX_OP 2 +.Os +.Sh NAME +.Nm _umtx_op +.Nd interface for implementation of userspace threading synchronization primitives +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/umtx.h +.Ft int +.Fn _umtx_op "void *obj" "int op" "u_long val" "void *uaddr" "void *uaddr2" +.Sh DESCRIPTION +The +.Fn _umtx_op +system call provides kernel support for userspace implementation of +the threading synchronization primitives. +The +.Lb libthr +uses the syscall to implement +.St -p1003.1-2001 +pthread locks, like mutexes, condition variables and so on. +.Ss STRUCTURES +The operations, performed by the +.Fn _umtx_op +syscall, operate on userspace objects which are described +by the following structures. +Reserved fields and paddings are omitted. +All objects require ABI-mandated alignment, but this is not currently +enforced consistently on all architectures. +.Pp +The following flags are defined for flag fields of all structures: +.Bl -tag -width indent +.It Dv USYNC_PROCESS_SHARED +Allow selection of the process-shared sleep queue for the thread sleep +container, when the lock ownership cannot be granted immediately, +and the operation must sleep. +The process-shared or process-private sleep queue is selected based on +the attributes of the memory mapping which contains the first byte of +the structure, see +.Xr mmap 2 . +Otherwise, if the flag is not specified, the process-private sleep queue +is selected regardless of the memory mapping attributes, as an optimization. +.Pp +See the +.Sx SLEEP QUEUES +subsection below for more details on sleep queues. +.El +.Bl -hang -offset indent +.It Sy Mutex +.Bd -literal +struct umutex { + volatile lwpid_t m_owner; + uint32_t m_flags; + uint32_t m_ceilings[2]; + uintptr_t m_rb_lnk; +}; +.Ed +.Pp +The +.Dv m_owner +field is the actual lock. +It contains either the thread identifier of the lock owner in the +locked state, or zero when the lock is unowned. +The highest bit set indicates that there is contention on the lock. +The constants are defined for special values: +.Bl -tag -width indent +.It Dv UMUTEX_UNOWNED +Zero, the value stored in the unowned lock. +.It Dv UMUTEX_CONTESTED +The contention indicator. +.It Dv UMUTEX_RB_OWNERDEAD +A thread owning the robust mutex terminated. +The mutex is in unlocked state. +.It Dv UMUTEX_RB_NOTRECOV +The robust mutex is in a non-recoverable state. +It cannot be locked until reinitialized. +.El +.Pp +The +.Dv m_flags +field may contain the following umutex-specific flags, in addition to +the common flags: +.Bl -tag -width indent +.It Dv UMUTEX_PRIO_INHERIT +Mutex implements +.Em Priority Inheritance +protocol. +.It Dv UMUTEX_PRIO_PROTECT +Mutex implements +.Em Priority Protection +protocol. +.It Dv UMUTEX_ROBUST +Mutex is robust, as described in the +.Sx ROBUST UMUTEXES +section below. +.It Dv UMUTEX_NONCONSISTENT +Robust mutex is in a transient non-consistent state. +Not used by kernel. +.El +.Pp +In the manual page, mutexes not having +.Dv UMUTEX_PRIO_INHERIT +and +.Dv UMUTEX_PRIO_PROTECT +flags set, are called normal mutexes. +Each type of mutex +.Pq normal, priority-inherited, and priority-protected +has a separate sleep queue associated +with the given key. +.Pp +For priority protected mutexes, the +.Dv m_ceilings +array contains priority ceiling values. +The +.Dv m_ceilings[0] +is the ceiling value for the mutex, as specified by +.St -p1003.1-2008 +for the +.Em Priority Protected +mutex protocol. +The +.Dv m_ceilings[1] +is used only for the unlock of a priority protected mutex, when +unlock is done in an order other than the reversed lock order. +In this case, +.Dv m_ceilings[1] +must contain the ceiling value for the last locked priority protected +mutex, for proper priority reassignment. +If, instead, the unlocking mutex was the last priority propagated +mutex locked by the thread, +.Dv m_ceilings[1] +should contain \-1. +This is required because kernel does not maintain the ordered lock list. +.It Sy Condition variable +.Bd -literal +struct ucond { + volatile uint32_t c_has_waiters; + uint32_t c_flags; + uint32_t c_clockid; +}; +.Ed +.Pp +A non-zero +.Dv c_has_waiters +value indicates that there are in-kernel waiters for the condition, +executing the +.Dv UMTX_OP_CV_WAIT +request. +.Pp +The +.Dv c_flags +field contains flags. +Only the common flags +.Pq Dv USYNC_PROCESS_SHARED +are defined for ucond. +.Pp +The +.Dv c_clockid +member provides the clock identifier to use for timeout, when the +.Dv UMTX_OP_CV_WAIT +request has both the +.Dv CVWAIT_CLOCKID +flag and the timeout specified. +Valid clock identifiers are a subset of those for +.Xr clock_gettime 2 : +.Bl -bullet -compact +.It +.Dv CLOCK_MONOTONIC +.It +.Dv CLOCK_MONOTONIC_FAST +.It +.Dv CLOCK_MONOTONIC_PRECISE +.It +.Dv CLOCK_PROF +.It +.Dv CLOCK_REALTIME +.It +.Dv CLOCK_REALTIME_FAST +.It +.Dv CLOCK_REALTIME_PRECISE +.It +.Dv CLOCK_SECOND +.It +.Dv CLOCK_TAI +.It +.Dv CLOCK_UPTIME +.It +.Dv CLOCK_UPTIME_FAST +.It +.Dv CLOCK_UPTIME_PRECISE +.It +.Dv CLOCK_VIRTUAL +.El +.It Sy Reader/writer lock +.Bd -literal +struct urwlock { + volatile int32_t rw_state; + uint32_t rw_flags; + uint32_t rw_blocked_readers; + uint32_t rw_blocked_writers; +}; +.Ed +.Pp +The +.Dv rw_state +field is the actual lock. +It contains both the flags and counter of the read locks which were +granted. +Names of the +.Dv rw_state +bits are following: +.Bl -tag -width indent +.It Dv URWLOCK_WRITE_OWNER +Write lock was granted. +.It Dv URWLOCK_WRITE_WAITERS +There are write lock waiters. +.It Dv URWLOCK_READ_WAITERS +There are read lock waiters. +.It Dv URWLOCK_READER_COUNT(c) +Returns the count of currently granted read locks. +.El +.Pp +At any given time there may be only one thread to which the writer lock +is granted on the +.Vt struct rwlock , +and no threads are granted read lock. +Or, at the given time, up to +.Dv URWLOCK_MAX_READERS +threads may be granted the read lock simultaneously, but write lock is +not granted to any thread. +.Pp +The following flags for the +.Dv rw_flags +member of +.Vt struct urwlock +are defined, in addition to the common flags: +.Bl -tag -width indent +.It Dv URWLOCK_PREFER_READER +If specified, immediately grant read lock requests when +.Dv urwlock +is already read-locked, even in presence of unsatisfied write +lock requests. +By default, if there is a write lock waiter, further read requests are +not granted, to prevent unfair write lock waiter starvation. +.El +.Pp +The +.Dv rw_blocked_readers +and +.Dv rw_blocked_writers +members contain the count of threads which are sleeping in kernel, +waiting for the associated request type to be granted. +The fields are used by kernel to update the +.Dv URWLOCK_READ_WAITERS +and +.Dv URWLOCK_WRITE_WAITERS +flags of the +.Dv rw_state +lock after requesting thread was woken up. +.It Sy Semaphore +.Bd -literal +struct _usem2 { + volatile uint32_t _count; + uint32_t _flags; +}; +.Ed +.Pp +The +.Dv _count +word represents a counting semaphore. +A non-zero value indicates an unlocked (posted) semaphore, while zero +represents the locked state. +The maximal supported semaphore count is +.Dv USEM_MAX_COUNT . +.Pp +The +.Dv _count +word, besides the counter of posts (unlocks), also contains the +.Dv USEM_HAS_WAITERS +bit, which indicates that locked semaphore has waiting threads. +.Pp +The +.Dv USEM_COUNT() +macro, applied to the +.Dv _count +word, returns the current semaphore counter, which is the number of posts +issued on the semaphore. +.Pp +The following bits for the +.Dv _flags +member of +.Vt struct _usem2 +are defined, in addition to the common flags: +.Bl -tag -width indent +.It Dv USEM_NAMED +Flag is ignored by kernel. +.El +.It Sy Timeout parameter +.Bd -literal +struct _umtx_time { + struct timespec _timeout; + uint32_t _flags; + uint32_t _clockid; +}; +.Ed +.Pp +Several +.Fn _umtx_op +operations allow the blocking time to be limited, failing the request +if it cannot be satisfied in the specified time period. +The timeout is specified by passing either the address of +.Vt struct timespec , +or its extended variant, +.Vt struct _umtx_time , +as the +.Fa uaddr2 +argument of +.Fn _umtx_op . +They are distinguished by the +.Fa uaddr +value, which must be equal to the size of the structure pointed to by +.Fa uaddr2 , +casted to +.Vt uintptr_t . +.Pp +The +.Dv _timeout +member specifies the time when the timeout should occur. +Legal values for clock identifier +.Dv _clockid +are shared with the +.Fa clock_id +argument to the +.Xr clock_gettime 2 +function, +and use the same underlying clocks. +The specified clock is used to obtain the current time value. +Interval counting is always performed by the monotonic wall clock. +.Pp +The +.Dv _flags +argument allows the following flags to further define the timeout behaviour: +.Bl -tag -width indent +.It Dv UMTX_ABSTIME +The +.Dv _timeout +value is the absolute time. +The thread will be unblocked and the request failed when specified +clock value is equal or exceeds the +.Dv _timeout. +.Pp +If the flag is absent, the timeout value is relative, that is the amount +of time, measured by the monotonic wall clock from the moment of the request +start. +.El +.El +.Ss SLEEP QUEUES +When a locking request cannot be immediately satisfied, the thread is +typically put to +.Em sleep , +which is a non-runnable state terminated by the +.Em wake +operation. +Lock operations include a +.Em try +variant which returns an error rather than sleeping if the lock cannot +be obtained. +Also, +.Fn _umtx_op +provides requests which explicitly put the thread to sleep. +.Pp +Wakes need to know which threads to make runnable, so sleeping threads +are grouped into containers called +.Em sleep queues . +A sleep queue is identified by a key, which for +.Fn _umtx_op +is defined as the physical address of some variable. +Note that the +.Em physical +address is used, which means that same variable mapped multiple +times will give one key value. +This mechanism enables the construction of +.Em process-shared +locks. +.Pp +A related attribute of the key is shareability. +Some requests always interpret keys as private for the current process, +creating sleep queues with the scope of the current process even if +the memory is shared. +Others either select the shareability automatically from the +mapping attributes, or take additional input as the +.Dv USYNC_PROCESS_SHARED +common flag. +This is done as optimization, allowing the lock scope to be limited +regardless of the kind of backing memory. +.Pp +Only the address of the start byte of the variable specified as key is +important for determining corresponding sleep queue. +The size of the variable does not matter, so, for example, sleep on the same +address interpreted as +.Vt uint32_t +and +.Vt long +on a little-endian 64-bit platform would collide. +.Pp +The last attribute of the key is the object type. +The sleep queue to which a sleeping thread is assigned is an individual +one for simple wait requests, mutexes, rwlocks, condvars and other +primitives, even when the physical address of the key is same. +.Pp +When waking up a limited number of threads from a given sleep queue, +the highest priority threads that have been blocked for the longest on +the queue are selected. +.Ss ROBUST UMUTEXES +The +.Em robust umutexes +are provided as a substrate for a userspace library to implement +.Tn POSIX +robust mutexes. +A robust umutex must have the +.Dv UMUTEX_ROBUST +flag set. +.Pp +On thread termination, the kernel walks two lists of mutexes. +The two lists head addresses must be provided by a prior call to +.Dv UMTX_OP_ROBUST_LISTS +request. +The lists are singly-linked. +The link to next element is provided by the +.Dv m_rb_lnk +member of the +.Vt struct umutex . +.Pp +Robust list processing is aborted if the kernel finds a mutex +with any of the following conditions: +.Bl -dash -offset indent -compact +.It +the +.Dv UMUTEX_ROBUST +flag is not set +.It +not owned by the current thread, except when the mutex is pointed to +by the +.Dv robust_inactive +member of the +.Vt struct umtx_robust_lists_params , +registered for the current thread +.It +the combination of mutex flags is invalid +.It +read of the umutex memory faults +.It +the list length limit described in +.Xr libthr 3 +is reached. +.El +.Pp +Every mutex in both lists is unlocked as if the +.Dv UMTX_OP_MUTEX_UNLOCK +request is performed on it, but instead of the +.Dv UMUTEX_UNOWNED +value, the +.Dv m_owner +field is written with the +.Dv UMUTEX_RB_OWNERDEAD +value. +When a mutex in the +.Dv UMUTEX_RB_OWNERDEAD +state is locked by kernel due to the +.Dv UMTX_OP_MUTEX_TRYLOCK +and +.Dv UMTX_OP_MUTEX_LOCK +requests, the lock is granted and +.Er EOWNERDEAD +error is returned. +.Pp +Also, the kernel handles the +.Dv UMUTEX_RB_NOTRECOV +value of +.Dv the m_owner +field specially, always returning the +.Er ENOTRECOVERABLE +error for lock attempts, without granting the lock. +.Ss OPERATIONS +The following operations, requested by the +.Fa op +argument to the function, are implemented: +.Bl -tag -width indent +.It Dv UMTX_OP_WAIT +Wait. +The arguments for the request are: +.Bl -tag -width "obj" +.It Fa obj +Pointer to a variable of type +.Vt long . +.It Fa val +Current value of the +.Dv *obj . +.El +.Pp +The current value of the variable pointed to by the +.Fa obj +argument is compared with the +.Fa val . +If they are equal, the requesting thread is put to interruptible sleep +until woken up or the optionally specified timeout expires. +.Pp +The comparison and sleep are atomic. +In other words, if another thread writes a new value to +.Dv *obj +and then issues +.Dv UMTX_OP_WAKE , +the request is guaranteed to not miss the wakeup, +which might otherwise happen between comparison and blocking. +.Pp +The physical address of memory where the +.Fa *obj +variable is located, is used as a key to index sleeping threads. +.Pp +The read of the current value of the +.Dv *obj +variable is not guarded by barriers. +In particular, it is the user's duty to ensure the lock acquire +and release memory semantics, if the +.Dv UMTX_OP_WAIT +and +.Dv UMTX_OP_WAKE +requests are used as a substrate for implementing a simple lock. +.Pp +The request is not restartable. +An unblocked signal delivered during the wait always results in sleep +interruption and +.Er EINTR +error. +.Pp +Optionally, a timeout for the request may be specified. +.It Dv UMTX_OP_WAKE +Wake the threads possibly sleeping due to +.Dv UMTX_OP_WAIT . +The arguments for the request are: +.Bl -tag -width "obj" +.It Fa obj +Pointer to a variable, used as a key to find sleeping threads. +.It Fa val +Up to +.Fa val +threads are woken up by this request. +Specify +.Dv INT_MAX +to wake up all waiters. +.El +.It Dv UMTX_OP_MUTEX_TRYLOCK +Try to lock umutex. +The arguments to the request are: +.Bl -tag -width "obj" +.It Fa obj +Pointer to the umutex. +.El +.Pp +Operates same as the +.Dv UMTX_OP_MUTEX_LOCK +request, but returns +.Er EBUSY +instead of sleeping if the lock cannot be obtained immediately. +.It Dv UMTX_OP_MUTEX_LOCK +Lock umutex. +The arguments to the request are: +.Bl -tag -width "obj" +.It Fa obj +Pointer to the umutex. +.El +.Pp +Locking is performed by writing the current thread id into the +.Dv m_owner +word of the +.Vt struct umutex . +The write is atomic, preserves the +.Dv UMUTEX_CONTESTED +contention indicator, and provides the acquire barrier for +lock entrance semantic. +.Pp +If the lock cannot be obtained immediately because another thread owns +the lock, the current thread is put to sleep, with +.Dv UMUTEX_CONTESTED +bit set before. +Upon wake up, the lock conditions are re-tested. +.Pp +The request adheres to the priority protection or inheritance protocol +of the mutex, specified by the +.Dv UMUTEX_PRIO_PROTECT +or +.Dv UMUTEX_PRIO_INHERIT +flag, respectively. +.Pp +Optionally, a timeout for the request may be specified. +.Pp +A request with a timeout specified is not restartable. +An unblocked signal delivered during the wait always results in sleep +interruption and +.Er EINTR +error. +A request without timeout specified is always restarted after return +from a signal handler. +.It Dv UMTX_OP_MUTEX_UNLOCK +Unlock umutex. +The arguments to the request are: +.Bl -tag -width "obj" +.It Fa obj +Pointer to the umutex. +.El +.Pp +Unlocks the mutex, by writing +.Dv UMUTEX_UNOWNED +(zero) value into +.Dv m_owner +word of the +.Vt struct umutex . +The write is done with a release barrier, to provide lock leave semantic. +.Pp +If there are threads sleeping in the sleep queue associated with the +umutex, one thread is woken up. +If more than one thread sleeps in the sleep queue, the +.Dv UMUTEX_CONTESTED +bit is set together with the write of the +.Dv UMUTEX_UNOWNED +value into +.Dv m_owner . +.Pp +The request adheres to the priority protection or inheritance protocol +of the mutex, specified by the +.Dv UMUTEX_PRIO_PROTECT +or +.Dv UMUTEX_PRIO_INHERIT +flag, respectively. +See description of the +.Dv m_ceilings +member of the +.Vt struct umutex +structure for additional details of the request operation on the +priority protected protocol mutex. +.It Dv UMTX_OP_SET_CEILING +Set ceiling for the priority protected umutex. +The arguments to the request are: +.Bl -tag -width "uaddr" +.It Fa obj +Pointer to the umutex. +.It Fa val +New ceiling value. +.It Fa uaddr +Address of a variable of type +.Vt uint32_t . +If not +.Dv NULL +and the update was successful, the previous ceiling value is +written to the location pointed to by +.Fa uaddr . +.El +.Pp +The request locks the umutex pointed to by the +.Fa obj +parameter, waiting for the lock if not immediately available. +After the lock is obtained, the new ceiling value +.Fa val +is written to the +.Dv m_ceilings[0] +member of the +.Vt struct umutex, +after which the umutex is unlocked. +.Pp +The locking does not adhere to the priority protect protocol, +to conform to the +.Tn POSIX +requirements for the +.Xr pthread_mutex_setprioceiling 3 +interface. +.It Dv UMTX_OP_CV_WAIT +Wait for a condition. +The arguments to the request are: +.Bl -tag -width "uaddr2" +.It Fa obj +Pointer to the +.Vt struct ucond . +.It Fa val +Request flags, see below. +.It Fa uaddr +Pointer to the umutex. +.It Fa uaddr2 +Optional pointer to a +.Vt struct timespec +for timeout specification. +.El +.Pp +The request must be issued by the thread owning the mutex pointed to +by the +.Fa uaddr +argument. +The +.Dv c_hash_waiters +member of the +.Vt struct ucond , +pointed to by the +.Fa obj +argument, is set to an arbitrary non-zero value, after which the +.Fa uaddr +mutex is unlocked (following the appropriate protocol), and +the current thread is put to sleep on the sleep queue keyed by +the +.Fa obj +argument. +The operations are performed atomically. +It is guaranteed to not miss a wakeup from +.Dv UMTX_OP_CV_SIGNAL +or +.Dv UMTX_OP_CV_BROADCAST +sent between mutex unlock and putting the current thread on the sleep queue. +.Pp +Upon wakeup, if the timeout expired and no other threads are sleeping in +the same sleep queue, the +.Dv c_hash_waiters +member is cleared. +After wakeup, the +.Fa uaddr +umutex is not relocked. +.Pp +The following flags are defined: +.Bl -tag -width "CVWAIT_CLOCKID" +.It Dv CVWAIT_ABSTIME +Timeout is absolute. +.It Dv CVWAIT_CLOCKID +Clockid is provided. +.El +.Pp +Optionally, a timeout for the request may be specified. +Unlike other requests, the timeout value is specified directly by a +.Vt struct timespec , +pointed to by the +.Fa uaddr2 +argument. +If the +.Dv CVWAIT_CLOCKID +flag is provided, the timeout uses the clock from the +.Dv c_clockid +member of the +.Vt struct ucond , +pointed to by +.Fa obj +argument. +Otherwise, +.Dv CLOCK_REALTIME +is used, regardless of the clock identifier possibly specified in the +.Vt struct _umtx_time . +If the +.Dv CVWAIT_ABSTIME +flag is supplied, the timeout specifies absolute time value, otherwise +it denotes a relative time interval. +.Pp +The request is not restartable. +An unblocked signal delivered during +the wait always results in sleep interruption and +.Er EINTR +error. +.It Dv UMTX_OP_CV_SIGNAL +Wake up one condition waiter. +The arguments to the request are: +.Bl -tag -width "obj" +.It Fa obj +Pointer to +.Vt struct ucond . +.El +.Pp +The request wakes up at most one thread sleeping on the sleep queue keyed +by the +.Fa obj +argument. +If the woken up thread was the last on the sleep queue, the +.Dv c_has_waiters +member of the +.Vt struct ucond +is cleared. +.It Dv UMTX_OP_CV_BROADCAST +Wake up all condition waiters. +The arguments to the request are: +.Bl -tag -width "obj" +.It Fa obj +Pointer to +.Vt struct ucond . +.El +.Pp +The request wakes up all threads sleeping on the sleep queue keyed by the +.Fa obj +argument. +The +.Dv c_has_waiters +member of the +.Vt struct ucond +is cleared. +.It Dv UMTX_OP_WAIT_UINT +Same as +.Dv UMTX_OP_WAIT , +but the type of the variable pointed to by +.Fa obj +is +.Vt u_int +.Pq a 32-bit integer . +.It Dv UMTX_OP_RW_RDLOCK +Read-lock a +.Vt struct rwlock +lock. +The arguments to the request are: +.Bl -tag -width "obj" +.It Fa obj +Pointer to the lock (of type +.Vt struct rwlock ) +to be read-locked. +.It Fa val +Additional flags to augment locking behaviour. +The valid flags in the +.Fa val +argument are: +.Bl -tag -width indent +.It Dv URWLOCK_PREFER_READER +.El +.El +.Pp +The request obtains the read lock on the specified +.Vt struct rwlock +by incrementing the count of readers in the +.Dv rw_state +word of the structure. +If the +.Dv URWLOCK_WRITE_OWNER +bit is set in the word +.Dv rw_state , +the lock was granted to a writer which has not yet relinquished +its ownership. +In this case the current thread is put to sleep until it makes sense to +retry. +.Pp +If the +.Dv URWLOCK_PREFER_READER +flag is set either in the +.Dv rw_flags +word of the structure, or in the +.Fa val +argument of the request, the presence of the threads trying to obtain +the write lock on the same structure does not prevent the current thread +from trying to obtain the read lock. +Otherwise, if the flag is not set, and the +.Dv URWLOCK_WRITE_WAITERS +flag is set in +.Dv rw_state , +the current thread does not attempt to obtain read-lock. +Instead it sets the +.Dv URWLOCK_READ_WAITERS +in the +.Dv rw_state +word and puts itself to sleep on corresponding sleep queue. +Upon wakeup, the locking conditions are re-evaluated. +.Pp +Optionally, a timeout for the request may be specified. +.Pp +The request is not restartable. +An unblocked signal delivered during the wait always results in sleep +interruption and +.Er EINTR +error. +.It Dv UMTX_OP_RW_WRLOCK +Write-lock a +.Vt struct rwlock +lock. +The arguments to the request are: +.Bl -tag -width "obj" +.It Fa obj +Pointer to the lock (of type +.Vt struct rwlock ) +to be write-locked. +.El +.Pp +The request obtains a write lock on the specified +.Vt struct rwlock , +by setting the +.Dv URWLOCK_WRITE_OWNER +bit in the +.Dv rw_state +word of the structure. +If there is already a write lock owner, as indicated by the +.Dv URWLOCK_WRITE_OWNER +bit being set, or there are read lock owners, as indicated +by the read-lock counter, the current thread does not attempt to +obtain the write-lock. +Instead it sets the +.Dv URWLOCK_WRITE_WAITERS +in the +.Dv rw_state +word and puts itself to sleep on corresponding sleep queue. +Upon wakeup, the locking conditions are re-evaluated. +.Pp +Optionally, a timeout for the request may be specified. +.Pp +The request is not restartable. +An unblocked signal delivered during the wait always results in sleep +interruption and +.Er EINTR +error. +.It Dv UMTX_OP_RW_UNLOCK +Unlock rwlock. +The arguments to the request are: +.Bl -tag -width "obj" +.It Fa obj +Pointer to the lock (of type +.Vt struct rwlock ) +to be unlocked. +.El +.Pp +The unlock type (read or write) is determined by the +current lock state. +Note that the +.Vt struct rwlock +does not save information about the identity of the thread which +acquired the lock. +.Pp +If there are pending writers after the unlock, and the +.Dv URWLOCK_PREFER_READER +flag is not set in the +.Dv rw_flags +member of the +.Fa *obj +structure, one writer is woken up, selected as described in the +.Sx SLEEP QUEUES +subsection. +If the +.Dv URWLOCK_PREFER_READER +flag is set, a pending writer is woken up only if there is +no pending readers. +.Pp +If there are no pending writers, or, in the case that the +.Dv URWLOCK_PREFER_READER +flag is set, then all pending readers are woken up by unlock. +.It Dv UMTX_OP_WAIT_UINT_PRIVATE +Same as +.Dv UMTX_OP_WAIT_UINT , +but unconditionally select the process-private sleep queue. +.It Dv UMTX_OP_WAKE_PRIVATE +Same as +.Dv UMTX_OP_WAKE , +but unconditionally select the process-private sleep queue. +.It Dv UMTX_OP_MUTEX_WAIT +Wait for mutex availability. +The arguments to the request are: +.Bl -tag -width "obj" +.It Fa obj +Address of the mutex. +.El +.Pp +Similarly to the +.Dv UMTX_OP_MUTEX_LOCK , +put the requesting thread to sleep if the mutex lock cannot be obtained +immediately. +The +.Dv UMUTEX_CONTESTED +bit is set in the +.Dv m_owner +word of the mutex to indicate that there is a waiter, before the thread +is added to the sleep queue. +Unlike the +.Dv UMTX_OP_MUTEX_LOCK +request, the lock is not obtained. +.Pp +The operation is not implemented for priority protected and +priority inherited protocol mutexes. +.Pp +Optionally, a timeout for the request may be specified. +.Pp +A request with a timeout specified is not restartable. +An unblocked signal delivered during the wait always results in sleep +interruption and +.Er EINTR +error. +A request without a timeout automatically restarts if the signal disposition +requested restart via the +.Dv SA_RESTART +flag in +.Vt struct sigaction +member +.Dv sa_flags . +.It Dv UMTX_OP_NWAKE_PRIVATE +Wake up a batch of sleeping threads. +The arguments to the request are: +.Bl -tag -width "obj" +.It Fa obj +Pointer to the array of pointers. +.It Fa val +Number of elements in the array pointed to by +.Fa obj . +.El +.Pp +For each element in the array pointed to by +.Fa obj , +wakes up all threads waiting on the +.Em private +sleep queue with the key +being the byte addressed by the array element. +.It Dv UMTX_OP_MUTEX_WAKE +Check if a normal umutex is unlocked and wake up a waiter. +The arguments for the request are: +.Bl -tag -width "obj" +.It Fa obj +Pointer to the umutex. +.El +.Pp +If the +.Dv m_owner +word of the mutex pointed to by the +.Fa obj +argument indicates unowned mutex, which has its contention indicator bit +.Dv UMUTEX_CONTESTED +set, clear the bit and wake up one waiter in the sleep queue associated +with the byte addressed by the +.Fa obj , +if any. +Only normal mutexes are supported by the request. +The sleep queue is always one for a normal mutex type. +.Pp +This request is deprecated in favor of +.Dv UMTX_OP_MUTEX_WAKE2 +since mutexes using it cannot synchronize their own destruction. +That is, the +.Dv m_owner +word has already been set to +.Dv UMUTEX_UNOWNED +when this request is made, +so that another thread can lock, unlock and destroy the mutex +(if no other thread uses the mutex afterwards). +Clearing the +.Dv UMUTEX_CONTESTED +bit may then modify freed memory. +.It Dv UMTX_OP_MUTEX_WAKE2 +Check if a umutex is unlocked and wake up a waiter. +The arguments for the request are: +.Bl -tag -width "obj" +.It Fa obj +Pointer to the umutex. +.It Fa val +The umutex flags. +.El +.Pp +The request does not read the +.Dv m_flags +member of the +.Vt struct umutex ; +instead, the +.Fa val +argument supplies flag information, in particular, to determine the +sleep queue where the waiters are found for wake up. +.Pp +If the mutex is unowned, one waiter is woken up. +.Pp +If the mutex memory cannot be accessed, all waiters are woken up. +.Pp +If there is more than one waiter on the sleep queue, or there is only +one waiter but the mutex is owned by a thread, the +.Dv UMUTEX_CONTESTED +bit is set in the +.Dv m_owner +word of the +.Vt struct umutex . +.It Dv UMTX_OP_SEM2_WAIT +Wait until semaphore is available. +The arguments to the request are: +.Bl -tag -width "obj" +.It Fa obj +Pointer to the semaphore (of type +.Vt struct _usem2 ) . +.It Fa uaddr +Size of the memory passed in via the +.Fa uaddr2 +argument. +.It Fa uaddr2 +Optional pointer to a structure of type +.Vt struct _umtx_time , +which may be followed by a structure of type +.Vt struct timespec . +.El +.Pp +Put the requesting thread onto a sleep queue if the semaphore counter +is zero. +If the thread is put to sleep, the +.Dv USEM_HAS_WAITERS +bit is set in the +.Dv _count +word to indicate waiters. +The function returns either due to +.Dv _count +indicating the semaphore is available (non-zero count due to post), +or due to a wakeup. +The return does not guarantee that the semaphore is available, +nor does it consume the semaphore lock on successful return. +.Pp +Optionally, a timeout for the request may be specified. +.Pp +A request with non-absolute timeout value is not restartable. +An unblocked signal delivered during such wait results in sleep +interruption and +.Er EINTR +error. +.Pp +If +.Dv UMTX_ABSTIME +was not set, and the operation was interrupted and the caller passed in a +.Fa uaddr2 +large enough to hold a +.Vt struct timespec +following the initial +.Vt struct _umtx_time , +then the +.Vt struct timespec +is updated to contain the unslept amount. +.It Dv UMTX_OP_SEM2_WAKE +Wake up waiters on semaphore lock. +The arguments to the request are: +.Bl -tag -width "obj" +.It Fa obj +Pointer to the semaphore (of type +.Vt struct _usem2 ) . +.El +.Pp +The request wakes up one waiter for the semaphore lock. +The function does not increment the semaphore lock count. +If the +.Dv USEM_HAS_WAITERS +bit was set in the +.Dv _count +word, and the last sleeping thread was woken up, the bit is cleared. +.It Dv UMTX_OP_SHM +Manage anonymous +.Tn POSIX +shared memory objects (see +.Xr shm_open 2 ) , +which can be attached to a byte of physical memory, mapped into the +process address space. +The objects are used to implement process-shared locks in +.Dv libthr . +.Pp +The +.Fa val +argument specifies the sub-request of the +.Dv UMTX_OP_SHM +request: +.Bl -tag -width indent +.It Dv UMTX_SHM_CREAT +Creates the anonymous shared memory object, which can be looked up +with the specified key +.Fa uaddr . +If the object associated with the +.Fa uaddr +key already exists, it is returned instead of creating a new object. +The object's size is one page. +On success, the file descriptor referencing the object is returned. +The descriptor can be used for mapping the object using +.Xr mmap 2 , +or for other shared memory operations. +.It Dv UMTX_SHM_LOOKUP +Same as +.Dv UMTX_SHM_CREATE +request, but if there is no shared memory object associated with +the specified key +.Fa uaddr , +an error is returned, and no new object is created. +.It Dv UMTX_SHM_DESTROY +De-associate the shared object with the specified key +.Fa uaddr . +The object is destroyed after the last open file descriptor is closed +and the last mapping for it is destroyed. +.It Dv UMTX_SHM_ALIVE +Checks whether there is a live shared object associated with the +supplied key +.Fa uaddr . +Returns zero if there is, and an error otherwise. +This request is an optimization of the +.Dv UMTX_SHM_LOOKUP +request. +It is cheaper when only the liveness of the associated object is asked +for, since no file descriptor is installed in the process fd table +on success. +.El +.Pp +The +.Fa uaddr +argument specifies the virtual address, which backing physical memory +byte identity is used as a key for the anonymous shared object +creation or lookup. +.It Dv UMTX_OP_ROBUST_LISTS +Register the list heads for the current thread's robust mutex lists. +The arguments to the request are: +.Bl -tag -width "uaddr" +.It Fa val +Size of the structure passed in the +.Fa uaddr +argument. +.It Fa uaddr +Pointer to the structure of type +.Vt struct umtx_robust_lists_params . +.El +.Pp +The structure is defined as +.Bd -literal +struct umtx_robust_lists_params { + uintptr_t robust_list_offset; + uintptr_t robust_priv_list_offset; + uintptr_t robust_inact_offset; +}; +.Ed +.Pp +The +.Dv robust_list_offset +member contains address of the first element in the list of locked +robust shared mutexes. +The +.Dv robust_priv_list_offset +member contains address of the first element in the list of locked +robust private mutexes. +The private and shared robust locked lists are split to allow fast +termination of the shared list on fork, in the child. +.Pp +The +.Dv robust_inact_offset +contains a pointer to the mutex which might be locked in nearby future, +or might have been just unlocked. +It is typically set by the lock or unlock mutex implementation code +around the whole operation, since lists can be only changed race-free +when the thread owns the mutex. +The kernel inspects the +.Dv robust_inact_offset +in addition to walking the shared and private lists. +Also, the mutex pointed to by +.Dv robust_inact_offset +is handled more loosely at the thread termination time, +than other mutexes on the list. +That mutex is allowed to be not owned by the current thread, +in which case list processing is continued. +See +.Sx ROBUST UMUTEXES +subsection for details. +.It Dv UMTX_OP_GET_MIN_TIMEOUT +Writes out the current value of minimal umtx operations timeout, +in nanoseconds, into the long integer variable pointed to by +.Fa uaddr1 . +.It Dv UMTX_OP_SET_MIN_TIMEOUT +Set the minimal amount of time, in nanoseconds, the thread is required +to sleep for umtx operations specifying a timeout using absolute clocks. +The value is taken from the +.Fa val +argument of the call. +Zero means no minimum. +.El +.Pp +The +.Fa op +argument may be a bitwise OR of a single command from above with one or more of +the following flags: +.Bl -tag -width indent +.It Dv UMTX_OP__I386 +Request i386 ABI compatibility from the native +.Nm +system call. +Specifically, this implies that: +.Bl -hang -offset indent +.It +.Fa obj +arguments that point to a word, point to a 32-bit integer. +.It +The +.Dv UMTX_OP_NWAKE_PRIVATE +.Fa obj +argument is a pointer to an array of 32-bit pointers. +.It +The +.Dv m_rb_lnk +member of +.Vt struct umutex +is a 32-bit pointer. +.It +.Vt struct timespec +uses a 32-bit time_t. +.El +.Pp +.Dv UMTX_OP__32BIT +has no effect if this flag is set. +This flag is valid for all architectures, but it is ignored on i386. +.It Dv UMTX_OP__32BIT +Request non-i386, 32-bit ABI compatibility from the native +.Nm +system call. +Specifically, this implies that: +.Bl -hang -offset indent +.It +.Fa obj +arguments that point to a word, point to a 32-bit integer. +.It +The +.Dv UMTX_OP_NWAKE_PRIVATE +.Fa obj +argument is a pointer to an array of 32-bit pointers. +.It +The +.Dv m_rb_lnk +member of +.Vt struct umutex +is a 32-bit pointer. +.It +.Vt struct timespec +uses a 64-bit time_t. +.El +.Pp +This flag has no effect if +.Dv UMTX_OP__I386 +is set. +This flag is valid for all architectures. +.El +.Pp +Note that if any 32-bit ABI compatibility is being requested, then care must be +taken with robust lists. +A single thread may not mix 32-bit compatible robust lists with native +robust lists. +The first +.Dv UMTX_OP_ROBUST_LISTS +call in a given thread determines which ABI that thread will use for robust +lists going forward. +.Sh RETURN VALUES +If successful, +all requests, except +.Dv UMTX_SHM_CREAT +and +.Dv UMTX_SHM_LOOKUP +sub-requests of the +.Dv UMTX_OP_SHM +request, will return zero. +The +.Dv UMTX_SHM_CREAT +and +.Dv UMTX_SHM_LOOKUP +return a shared memory file descriptor on success. +On error \-1 is returned, and the +.Va errno +variable is set to indicate the error. +.Sh ERRORS +The +.Fn _umtx_op +operations can fail with the following errors: +.Bl -tag -width "[ETIMEDOUT]" +.It Bq Er EFAULT +One of the arguments point to invalid memory. +.It Bq Er EINVAL +The clock identifier, specified for the +.Vt struct _umtx_time +timeout parameter, or in the +.Dv c_clockid +member of +.Vt struct ucond, +is invalid. +.It Bq Er EINVAL +The type of the mutex, encoded by the +.Dv m_flags +member of +.Vt struct umutex , +is invalid. +.It Bq Er EINVAL +The +.Dv m_owner +member of the +.Vt struct umutex +has changed the lock owner thread identifier during unlock. +.It Bq Er EINVAL +The +.Dv timeout.tv_sec +or +.Dv timeout.tv_nsec +member of +.Vt struct _umtx_time +is less than zero, or +.Dv timeout.tv_nsec +is greater than 1000000000. +.It Bq Er EINVAL +The +.Fa op +argument specifies invalid operation. +.It Bq Er EINVAL +The +.Fa uaddr +argument for the +.Dv UMTX_OP_SHM +request specifies invalid operation. +.It Bq Er EINVAL +The +.Dv UMTX_OP_SET_CEILING +request specifies non priority protected mutex. +.It Bq Er EINVAL +The new ceiling value for the +.Dv UMTX_OP_SET_CEILING +request, or one or more of the values read from the +.Dv m_ceilings +array during lock or unlock operations, is greater than +.Dv RTP_PRIO_MAX . +.It Bq Er EPERM +Unlock attempted on an object not owned by the current thread. +.It Bq Er EOWNERDEAD +The lock was requested on an umutex where the +.Dv m_owner +field was set to the +.Dv UMUTEX_RB_OWNERDEAD +value, indicating terminated robust mutex. +The lock was granted to the caller, so this error in fact +indicates success with additional conditions. +.It Bq Er ENOTRECOVERABLE +The lock was requested on an umutex which +.Dv m_owner +field is equal to the +.Dv UMUTEX_RB_NOTRECOV +value, indicating abandoned robust mutex after termination. +The lock was not granted to the caller. +.It Bq Er ENOTTY +The shared memory object, associated with the address passed to the +.Dv UMTX_SHM_ALIVE +sub-request of +.Dv UMTX_OP_SHM +request, was destroyed. +.It Bq Er ESRCH +For the +.Dv UMTX_SHM_LOOKUP , +.Dv UMTX_SHM_DESTROY , +and +.Dv UMTX_SHM_ALIVE +sub-requests of the +.Dv UMTX_OP_SHM +request, there is no shared memory object associated with the provided key. +.It Bq Er ENOMEM +The +.Dv UMTX_SHM_CREAT +sub-request of the +.Dv UMTX_OP_SHM +request cannot be satisfied, because allocation of the shared memory object +would exceed the +.Dv RLIMIT_UMTXP +resource limit, see +.Xr setrlimit 2 . +.It Bq Er EAGAIN +The maximum number of readers +.Dv ( URWLOCK_MAX_READERS ) +were already granted ownership of the given +.Vt struct rwlock +for read. +.It Bq Er EBUSY +A try mutex lock operation was not able to obtain the lock. +.It Bq Er ETIMEDOUT +The request specified a timeout in the +.Fa uaddr +and +.Fa uaddr2 +arguments, and timed out before obtaining the lock or being woken up. +.It Bq Er EINTR +A signal was delivered during wait, for a non-restartable operation. +Operations with timeouts are typically non-restartable, but timeouts +specified in absolute time may be restartable. +.It Bq Er ERESTART +A signal was delivered during wait, for a restartable operation. +Mutex lock requests without timeout specified are restartable. +The error is not returned to userspace code since restart +is handled by usual adjustment of the instruction counter. +.El +.Sh SEE ALSO +.Xr clock_gettime 2 , +.Xr mmap 2 , +.Xr setrlimit 2 , +.Xr shm_open 2 , +.Xr sigaction 2 , +.Xr thr_exit 2 , +.Xr thr_kill 2 , +.Xr thr_kill2 2 , +.Xr thr_new 2 , +.Xr thr_self 2 , +.Xr thr_set_name 2 , +.Xr signal 3 +.Sh STANDARDS +The +.Fn _umtx_op +system call is non-standard and is used by the +.Lb libthr +to implement +.St -p1003.1-2001 +.Xr pthread 3 +functionality. +.Sh BUGS +A window between a unlocking robust mutex and resetting the pointer in the +.Dv robust_inact_offset +member of the registered +.Vt struct umtx_robust_lists_params +allows another thread to destroy the mutex, thus making the kernel inspect +freed or reused memory. +The +.Li libthr +implementation is only vulnerable to this race when operating on +a shared mutex. +A possible fix for the current implementation is to strengthen the checks +for shared mutexes before terminating them, in particular, verifying +that the mutex memory is mapped from a shared memory object allocated +by the +.Dv UMTX_OP_SHM +request. +This is not done because it is believed that the race is adequately +covered by other consistency checks, while adding the check would +prevent alternative implementations of +.Li libpthread . diff --git a/lib/libsys/_umtx_op_err.c b/lib/libsys/_umtx_op_err.c new file mode 100644 index 000000000000..8281b8af7110 --- /dev/null +++ b/lib/libsys/_umtx_op_err.c @@ -0,0 +1,39 @@ +/*- + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (c) 2005 David Xu <davidxu@freebsd.org> + * All rights reserved. + * + * 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 unmodified, 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 ``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 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. + */ + +#include <sys/types.h> +#include <sys/errno.h> +#include <sys/umtx.h> + +int +_umtx_op_err(void *obj, int op, u_long val, void *uaddr, void *uaddr2) +{ + if (_umtx_op(obj, op, val, uaddr, uaddr2) == -1) + return (errno); + return (0); +} diff --git a/lib/libsys/aarch64/Makefile.sys b/lib/libsys/aarch64/Makefile.sys new file mode 100644 index 000000000000..04b95602c580 --- /dev/null +++ b/lib/libsys/aarch64/Makefile.sys @@ -0,0 +1,7 @@ +MIASM:= ${MIASM:Nfreebsd[467]_*} + +SRCS+= __vdso_gettc.c \ + sched_getcpu_gen.c + +MDASM= cerror.S \ + vfork.S diff --git a/lib/libsys/aarch64/SYS.h b/lib/libsys/aarch64/SYS.h new file mode 100644 index 000000000000..a2ff7af18b18 --- /dev/null +++ b/lib/libsys/aarch64/SYS.h @@ -0,0 +1,62 @@ +/*- + * Copyright (c) 2014 Andrew Turner + * Copyright (c) 2015 The FreeBSD Foundation + * + * This software was developed by Andrew Turner under + * sponsorship from the FreeBSD Foundation. + * + * 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. + */ + +#include <sys/syscall.h> +#include <machine/asm.h> + +#define _SYSCALL(name) \ + mov x8, SYS_ ## name; \ + svc 0 + +#ifndef _SYSCALL_BODY +/* + * Conditional jumps can only go up to one megabyte in either + * direction, and cerror can be located anywhere, so we have + * to jump around to use more capable unconditional branch + * instruction. + */ +#define _SYSCALL_BODY(name) \ + _SYSCALL(name); \ + b.cs 1f; \ + ret; \ +1: b cerror +#endif + +#define PSEUDO(name) \ +ENTRY(__sys_##name); \ + WEAK_REFERENCE(__sys_##name, _##name); \ + _SYSCALL_BODY(name); \ +END(__sys_##name) + +#define RSYSCALL(name) \ +ENTRY(__sys_##name); \ + WEAK_REFERENCE(__sys_##name, name); \ + WEAK_REFERENCE(__sys_##name, _##name); \ + _SYSCALL_BODY(name); \ +END(__sys_##name) diff --git a/lib/libsys/aarch64/__vdso_gettc.c b/lib/libsys/aarch64/__vdso_gettc.c new file mode 100644 index 000000000000..5c5963d0e757 --- /dev/null +++ b/lib/libsys/aarch64/__vdso_gettc.c @@ -0,0 +1,73 @@ +/*- + * Copyright (c) 2015 The FreeBSD Foundation + * + * This software was developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * 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. + */ + +#include <sys/types.h> +#include <sys/elf.h> +#include <sys/time.h> +#include <sys/vdso.h> +#include <machine/cpufunc.h> +#include <errno.h> +#include "libc_private.h" + +static inline uint64_t +cp15_cntvct_get(void) +{ + uint64_t reg; + + __asm __volatile("mrs %0, cntvct_el0" : "=r" (reg)); + return (reg); +} + +static inline uint64_t +cp15_cntpct_get(void) +{ + uint64_t reg; + + __asm __volatile("mrs %0, cntpct_el0" : "=r" (reg)); + return (reg); +} + +#pragma weak __vdso_gettc +int +__vdso_gettc(const struct vdso_timehands *th, u_int *tc) +{ + + if (th->th_algo != VDSO_TH_ALGO_ARM_GENTIM) + return (ENOSYS); + __asm __volatile("isb" : : : "memory"); + *tc = th->th_physical == 0 ? cp15_cntvct_get() : cp15_cntpct_get(); + return (0); +} + +#pragma weak __vdso_gettimekeep +int +__vdso_gettimekeep(struct vdso_timekeep **tk) +{ + + return (_elf_aux_info(AT_TIMEKEEP, tk, sizeof(*tk))); +} diff --git a/lib/libsys/aarch64/cerror.S b/lib/libsys/aarch64/cerror.S new file mode 100644 index 000000000000..85e75af8ec0d --- /dev/null +++ b/lib/libsys/aarch64/cerror.S @@ -0,0 +1,43 @@ +/*- + * Copyright (c) 2014 Andrew Turner + * + * 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. + * + */ + +#include <machine/asm.h> +#include <sys/elf_common.h> + +ENTRY(cerror) + .hidden cerror + sub sp, sp, #16 + stp x0, lr, [sp] + bl _C_LABEL(__error) + ldp x1, lr, [sp] + str w1, [x0] + movn x0, #0 + movn x1, #0 + add sp, sp, #16 + ret +END(cerror) + +GNU_PROPERTY_AARCH64_FEATURE_1_NOTE(GNU_PROPERTY_AARCH64_FEATURE_1_VAL) diff --git a/lib/libsys/aarch64/vfork.S b/lib/libsys/aarch64/vfork.S new file mode 100644 index 000000000000..03ae5a6325ba --- /dev/null +++ b/lib/libsys/aarch64/vfork.S @@ -0,0 +1,43 @@ +/*- + * Copyright (c) 2014 Andrew Turner + * + * 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. + * + */ + +#include <machine/asm.h> +#include <sys/elf_common.h> +#include "SYS.h" + +ENTRY(__sys_vfork) + WEAK_REFERENCE(__sys_vfork, vfork) + WEAK_REFERENCE(__sys_vfork, _vfork) + mov x2, lr + _SYSCALL(vfork) + b.cs cerror + sub x1, x1, #1 + and x0, x0, x1 + mov lr, x2 + ret +END(__sys_vfork) + +GNU_PROPERTY_AARCH64_FEATURE_1_NOTE(GNU_PROPERTY_AARCH64_FEATURE_1_VAL) diff --git a/lib/libsys/abort2.2 b/lib/libsys/abort2.2 new file mode 100644 index 000000000000..8073d5d747cc --- /dev/null +++ b/lib/libsys/abort2.2 @@ -0,0 +1,111 @@ +.\" Copyright (c) 2005 Wojciech A. Koszek <dunstan@FreeBSD.czest.pl> +.\" All rights reserved. +.\" +.\" 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. +.\" +.Dd September 30, 2006 +.Dt ABORT2 2 +.Os +.Sh NAME +.Nm abort2 +.Nd "abort process with diagnostics" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft void +.Fn abort2 "const char *why" "int nargs" "void **args" +.Sh DESCRIPTION +The +.Fn abort2 +system call causes the process to be killed and the specified diagnostic +message (with arguments) to be delivered by the kernel to the +.Xr syslogd 8 +daemon. +.Pp +The +.Fa why +argument points to a +.Dv NUL- Ns +terminated string specifying a reason of the program's termination +(maximum 128 characters long). +The +.Fa args +array contains pointers which will be logged numerically +(with the kernel's +.Ql %p +.Xr printf 9 +format). +The +.Fa nargs +argument specifies the number of pointers in +.Fa args +(maximum 16). +.Pp +The +.Fn abort2 +system call +is intended for use in situations where continuation of a process +is impossible or for other definitive reasons is unwanted, and normal +diagnostic channels cannot be trusted to deliver the message. +.Sh RETURN VALUES +The +.Fn abort2 +function +never returns. +.Pp +The process is killed with +.Dv SIGABRT +unless the arguments to +.Fn abort2 +are invalid, in which case +.Dv SIGKILL +is used. +.Sh EXAMPLES +.Bd -literal -compact +#include <stdlib.h> + +if (weight_kg > max_load) { + void *ptrs[3]; + + ptrs[0] = (void *)(intptr_t)weight_kg; + ptrs[1] = (void *)(intptr_t)max_load; + ptrs[2] = haystack; + abort2("Camel overloaded", 3, ptrs); +} +.Ed +.Sh SEE ALSO +.Xr abort 3 , +.Xr exit 3 +.Sh HISTORY +The +.Fn abort2 +system call first appeared in +.Fx 7.0 . +.Sh AUTHORS +.An -nosplit +The +.Fn abort2 +system call was designed by +.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org . +It was implemented by +.An Wojciech A. Koszek Aq Mt dunstan@freebsd.czest.pl . diff --git a/lib/libsys/accept.2 b/lib/libsys/accept.2 new file mode 100644 index 000000000000..2da2af066a5b --- /dev/null +++ b/lib/libsys/accept.2 @@ -0,0 +1,248 @@ +.\" Copyright (c) 1983, 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd May 17, 2025 +.Dt ACCEPT 2 +.Os +.Sh NAME +.Nm accept , +.Nm accept4 +.Nd accept a connection on a socket +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.Ft int +.Fn accept "int s" "struct sockaddr * restrict addr" "socklen_t * restrict addrlen" +.Ft int +.Fn accept4 "int s" "struct sockaddr * restrict addr" "socklen_t * restrict addrlen" "int flags" +.Sh DESCRIPTION +The argument +.Fa s +is a socket that has been created with +.Xr socket 2 , +bound to an address with +.Xr bind 2 , +and is listening for connections after a +.Xr listen 2 . +The +.Fn accept +system call extracts the first connection request on the +queue of pending connections, creates a new socket, +and allocates a new file descriptor for the socket which +inherits the state of the +.Dv O_NONBLOCK +and +.Dv O_ASYNC +properties and the destination of +.Dv SIGIO +and +.Dv SIGURG +signals from the original socket +.Fa s . +.Pp +The +.Fn accept4 +system call is similar, +but the +.Dv O_NONBLOCK +property of the new socket is instead determined by the +.Dv SOCK_NONBLOCK +flag in the +.Fa flags +argument, +the +.Dv O_ASYNC +property is cleared, +the signal destination is cleared +and the close-on-exec flag on the new file descriptor can be set via the +.Dv SOCK_CLOEXEC +flag in the +.Fa flags +argument. +Similarly, the +.Dv O_CLOFORK +property can be set via the +.Dv SOCK_CLOFORK +flag in the +.Fa flags +argument. +.Pp +If no pending connections are +present on the queue, and the original socket +is not marked as non-blocking, +.Fn accept +blocks the caller until a connection is present. +If the original socket +is marked non-blocking and no pending +connections are present on the queue, +.Fn accept +returns an error as described below. +The accepted socket +may not be used +to accept more connections. +The original socket +.Fa s +remains open. +.Pp +The argument +.Fa addr +is a result argument that is filled-in with +the address of the connecting entity, +as known to the communications layer. +The exact format of the +.Fa addr +argument is determined by the domain in which the communication +is occurring. +A null pointer may be specified for +.Fa addr +if the address information is not desired; +in this case, +.Fa addrlen +is not used and should also be null. +Otherwise, the +.Fa addrlen +argument +is a value-result argument; it should initially contain the +amount of space pointed to by +.Fa addr ; +on return it will contain the actual length (in bytes) of the +address returned. +This call +is used with connection-based socket types, currently with +.Dv SOCK_STREAM . +.Pp +It is possible to +.Xr select 2 +a socket for the purposes of doing an +.Fn accept +by selecting it for read. +.Pp +For certain protocols which require an explicit confirmation, +such as +.Tn ISO +or +.Tn DATAKIT , +.Fn accept +can be thought of +as merely dequeueing 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. +.Pp +For some applications, performance may be enhanced by using an +.Xr accept_filter 9 +to pre-process incoming connections. +.Pp +When using +.Fn accept , +portable programs should not rely on the +.Dv O_NONBLOCK +and +.Dv O_ASYNC +properties and the signal destination being inherited, +but should set them explicitly using +.Xr fcntl 2 ; +.Fn accept4 +sets these properties consistently, +but may not be fully portable across +.Ux +platforms. +.Sh RETURN VALUES +These calls return \-1 on error. +If they succeed, they return a non-negative +integer that is a descriptor for the accepted socket. +.Sh ERRORS +The +.Fn accept +and +.Fn accept4 +system calls will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The descriptor is invalid. +.It Bq Er EINTR +The +.Fn accept +operation was interrupted. +.It Bq Er EMFILE +The per-process descriptor table is full. +.It Bq Er ENFILE +The system file table is full. +.It Bq Er ENOTSOCK +The descriptor references a file, not a socket. +.It Bq Er EINVAL +.Xr listen 2 +has not been called on the socket descriptor. +.It Bq Er EFAULT +The +.Fa addr +argument is not in a writable part of the +user address space. +.It Bo Er EWOULDBLOCK Bc or Bq Er EAGAIN +The socket is marked non-blocking and no connections +are present to be accepted. +.It Bq Er ECONNABORTED +A connection arrived, but it was closed while waiting +on the listen queue. +.El +.Pp +The +.Fn accept4 +system call will also fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa flags +argument is invalid. +.El +.Sh SEE ALSO +.Xr bind 2 , +.Xr connect 2 , +.Xr getpeername 2 , +.Xr getsockname 2 , +.Xr listen 2 , +.Xr select 2 , +.Xr socket 2 , +.Xr accept_filter 9 +.Sh HISTORY +The +.Fn accept +system call appeared in +.Bx 4.2 . +.Pp +The +.Fn accept4 +system call appeared in +.Fx 10.0 . +.Pp +The +.Dv SOCK_CLOFORK +flag appeared in +.Fx 15.0 . diff --git a/lib/libsys/access.2 b/lib/libsys/access.2 new file mode 100644 index 000000000000..94a13dcc4dcf --- /dev/null +++ b/lib/libsys/access.2 @@ -0,0 +1,277 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd August 11, 2024 +.Dt ACCESS 2 +.Os +.Sh NAME +.Nm access , +.Nm eaccess , +.Nm faccessat +.Nd check accessibility of a file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn access "const char *path" "int mode" +.Ft int +.Fn eaccess "const char *path" "int mode" +.Ft int +.Fn faccessat "int fd" "const char *path" "int mode" "int flag" +.Sh DESCRIPTION +The +.Fn access , +.Fn eaccess +and +.Fn faccessat +system calls report whether an attempt to access the file designated +by their +.Fa path +in the manner described by their +.Fa mode +argument is likely to succeed. +The value of +.Fa mode +is either the bitwise-inclusive OR of the desired permissions +.Po +.Dv R_OK +for read permission, +.Dv W_OK +for write permission, and +.Dv X_OK +for execute / search permission +.Pc +or +.Dv F_OK +to simply check whether the file exists. +.Pp +For a number of reasons, these system calls cannot be relied upon to +give a correct and definitive answer. +They can at best provide an early indication of the expected outcome, +to be confirmed by actually attempting the operation. +For existence checks, either +.Xr stat 2 +or +.Xr lstat 2 +should be used instead. +See also +.Sx SECURITY CONSIDERATIONS +below. +.Pp +The +.Fn eaccess +system call uses +the effective user ID and the group access list +to authorize the request; +the +.Fn access +system call uses +the real user ID in place of the effective user ID, +the real group ID in place of the effective group ID, +and the rest of the group access list. +.Pp +See the +.Sx DEFINITIONS +section of +.Xr intro 2 +for additional information on file access permissions and real +vs. effective user and group IDs. +.Pp +The +.Fn faccessat +system call is equivalent to +.Fn access +except in the case where +.Fa path +specifies a relative path. +In this case the file whose accessibility is to be determined is +located relative to the directory associated with the file descriptor +.Fa fd +instead of the current working directory. +If +.Fn faccessat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is +identical to a call to +.Fn access . +Values for +.Fa flag +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.In fcntl.h : +.Bl -tag -width indent +.It Dv AT_EACCESS +The checks are performed using the effective user and group IDs, +like +.Fn eaccess , +instead of the real user and group ID, like +.Fn access . +.It Dv AT_RESOLVE_BENEATH +Only walk paths below the directory specified by the +.Ar fd +descriptor. +See the description of the +.Dv O_RESOLVE_BENEATH +flag in the +.Xr open 2 +manual page. +.It Dv AT_EMPTY_PATH +If the +.Fa path +argument is an empty string, operate on the file or directory +referenced by the descriptor +.Fa fd . +If +.Fa fd +is equal to +.Dv AT_FDCWD , +operate on the current working directory. +.It Dv AT_SYMLINK_NOFOLLOW +If +.Fa path +names a symbolic link, access of the symbolic link is evaluated. +.El +.Pp +Even if a process's real or effective user has appropriate privileges +and indicates success for +.Dv X_OK , +the file may not actually have execute permission bits set. +Likewise for +.Dv R_OK +and +.Dv W_OK . +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn access , +.Fn eaccess , +and +.Fn faccessat +system calls may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value of the +.Fa mode +argument is invalid. +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named file does not exist. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EROFS +Write access is requested for a file on a read-only file system. +.It Bq Er ETXTBSY +Write access is requested for a pure procedure (shared text) +file presently being executed. +.It Bq Er EACCES +Permission bits of the file mode do not permit the requested +access, or search permission is denied on a component of the +path prefix. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.El +.Pp +Also, the +.Fn faccessat +system call may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is +neither +.Dv AT_FDCWD +nor a valid file descriptor. +.It Bq Er EINVAL +The value of the +.Fa flag +argument is not valid. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.It Bq Er ENOTCAPABLE +.Fa path +is an absolute path, +or contained a ".." component leading to a +directory outside of the directory hierarchy specified by +.Fa fd , +and the process is in capability mode. +.El +.Sh SEE ALSO +.Xr chmod 2 , +.Xr intro 2 , +.Xr stat 2 +.Sh STANDARDS +The +.Fn access +system call is expected to conform to +.St -p1003.1-90 . +The +.Fn faccessat +system call follows The Open Group Extended API Set 2 specification. +.Sh HISTORY +The +.Fn access +function appeared in +.At v7 . +The +.Fn faccessat +system call appeared in +.Fx 8.0 . +.Sh SECURITY CONSIDERATIONS +The +.Fn access , +.Fn eaccess , +and +.Fn faccessat +system calls are subject to time-of-check-to-time-of-use races and +should not be relied upon for file permission enforcement purposes. +Instead, applications should perform the desired action using the +requesting user's credentials. diff --git a/lib/libsys/acct.2 b/lib/libsys/acct.2 new file mode 100644 index 000000000000..1fbc24e8fe81 --- /dev/null +++ b/lib/libsys/acct.2 @@ -0,0 +1,130 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd March 30, 2020 +.Dt ACCT 2 +.Os +.Sh NAME +.Nm acct +.Nd enable or disable process accounting +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn acct "const char *file" +.Sh DESCRIPTION +The +.Fn acct +system call enables or disables the collection of system accounting +records. +If the argument +.Fa file +is a null pointer, accounting is disabled. +If +.Fa file +is an +.Em existing +pathname (null-terminated), record collection is enabled and for +every process initiated which terminates under normal +conditions an accounting record is appended to +.Fa file . +Abnormal conditions of termination are reboots +or other fatal system problems. +Records for processes which never terminate cannot be +produced by +.Fn acct . +.Pp +For more information on the record structure used by +.Fn acct , +see +.In sys/acct.h +and +.Xr acct 5 . +.Pp +This call is permitted only to the super-user. +.Sh NOTES +Accounting is automatically disabled when the file system the +accounting file resides on runs out of space; it is enabled when +space once again becomes available. +The values controlling this behaviour can be modified using the following +.Xr sysctl 8 +variables: +.Bl -tag -width ".Va kern.acct_chkfreq" +.It Va kern.acct_chkfreq +Specifies the frequency (in seconds) with which free disk +space should be checked. +.It Va kern.acct_resume +The percentage of free disk space above which process +accounting will resume. +.It Va kern.acct_suspend +The percentage of free disk space below which process +accounting will suspend. +.El +.Sh RETURN VALUES +On error -1 is returned. +The file must exist and the call may be exercised only by the super-user. +.Sh ERRORS +The +.Fn acct +system call will fail if one of the following is true: +.Bl -tag -width Er +.It Bq Er EPERM +The caller is not the super-user. +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named file does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix, +or the path name is not a regular file. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EROFS +The named file resides on a read-only file system. +.It Bq Er EFAULT +The +.Fa file +argument +points outside the process's allocated address space. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.El +.Sh SEE ALSO +.Xr acct 5 , +.Xr accton 8 , +.Xr sa 8 +.Sh HISTORY +The +.Fn acct +function appeared in +.At v7 . diff --git a/lib/libsys/adjtime.2 b/lib/libsys/adjtime.2 new file mode 100644 index 000000000000..ee8befe09ca9 --- /dev/null +++ b/lib/libsys/adjtime.2 @@ -0,0 +1,106 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd May 13, 2021 +.Dt ADJTIME 2 +.Os +.Sh NAME +.Nm adjtime +.Nd "correct the time to allow synchronization of the system clock" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/time.h +.Ft int +.Fn adjtime "const struct timeval *delta" "struct timeval *olddelta" +.Sh DESCRIPTION +The +.Fn adjtime +system call +makes small adjustments to the system time, as returned by +.Xr gettimeofday 2 , +advancing or retarding it +by the time specified by the timeval +.Fa delta . +If +.Fa delta +is negative, the clock is +slowed down by incrementing it more slowly than normal until +the correction is complete. +If +.Fa delta +is positive, a larger increment than normal +is used. +The skew used to perform the correction is generally a fraction of one percent. +Thus, the time is always +a monotonically increasing function. +A time correction from an earlier call to +.Fn adjtime +may not be finished when +.Fn adjtime +is called again. +If +.Fa olddelta +is not a null pointer, +the structure pointed to will contain, upon return, the +number of microseconds still to be corrected +from the earlier call. +.Pp +This call may be used by time servers that synchronize the clocks +of computers in a local area network. +Such time servers would slow down the clocks of some machines +and speed up the clocks of others to bring them to the average network time. +.Pp +The +.Fn adjtime +system call +is restricted to the super-user. +.Sh RETURN VALUES +.Rv -std adjtime +.Sh ERRORS +The +.Fn adjtime +system call will fail if: +.Bl -tag -width Er +.It Bq Er EFAULT +An argument points outside the process's allocated address space. +.It Bq Er EPERM +The process's effective user ID is not that of the super-user. +.El +.Sh SEE ALSO +.Xr date 1 , +.Xr gettimeofday 2 +.Rs +.%T "TSP: The Time Synchronization Protocol for UNIX 4.3BSD" +.%A R. Gusella +.%A S. Zatti +.Re +.Sh HISTORY +The +.Fn adjtime +system call appeared in +.Bx 4.3 . diff --git a/lib/libsys/aio_cancel.2 b/lib/libsys/aio_cancel.2 new file mode 100644 index 000000000000..42d074054716 --- /dev/null +++ b/lib/libsys/aio_cancel.2 @@ -0,0 +1,115 @@ +.\" Copyright (c) 1999 Softweyr LLC. +.\" All rights reserved. +.\" +.\" 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 Softweyr LLC 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 Softweyr LLC 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. +.\" +.Dd January 19, 2000 +.Dt AIO_CANCEL 2 +.Os +.Sh NAME +.Nm aio_cancel +.Nd cancel an outstanding asynchronous I/O operation (REALTIME) +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In aio.h +.Ft int +.Fn aio_cancel "int fildes" "struct aiocb *iocb" +.Sh DESCRIPTION +The +.Fn aio_cancel +system call cancels the outstanding asynchronous +I/O request for the file descriptor specified in +.Fa fildes . +If +.Fa iocb +is specified, only that specific asynchronous I/O request is cancelled. +.Pp +Normal asynchronous notification occurs for cancelled requests. +Requests complete with an error result of +.Er ECANCELED . +.Sh RESTRICTIONS +The +.Fn aio_cancel +system call does not cancel asynchronous I/O requests for raw disk devices. +The +.Fn aio_cancel +system call will always return +.Dv AIO_NOTCANCELED +for file descriptors associated with raw disk devices. +.Sh RETURN VALUES +The +.Fn aio_cancel +system call returns -1 to indicate an error, or one of the following: +.Bl -tag -width Dv +.It Bq Dv AIO_CANCELED +All outstanding requests meeting the criteria specified were cancelled. +.It Bq Dv AIO_NOTCANCELED +Some requests were not cancelled, status for the requests should be +checked with +.Xr aio_error 2 . +.It Bq Dv AIO_ALLDONE +All of the requests meeting the criteria have finished. +.El +.Sh ERRORS +An error return from +.Fn aio_cancel +indicates: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fildes +argument +is an invalid file descriptor. +.El +.Sh SEE ALSO +.Xr aio_error 2 , +.Xr aio_read 2 , +.Xr aio_return 2 , +.Xr aio_suspend 2 , +.Xr aio_write 2 , +.Xr aio 4 +.Sh STANDARDS +The +.Fn aio_cancel +system call is expected to conform to the +.St -p1003.1 +standard. +.Sh HISTORY +The +.Fn aio_cancel +system call first appeared in +.Fx 3.0 . +The first functional implementation of +.Fn aio_cancel +appeared in +.Fx 4.0 . +.Sh AUTHORS +.An -nosplit +This +manual page was originally written by +.An Wes Peters Aq Mt wes@softweyr.com . +.An Christopher M Sedore Aq Mt cmsedore@maxwell.syr.edu +updated it when +.Fn aio_cancel +was implemented for +.Fx 4.0 . diff --git a/lib/libsys/aio_error.2 b/lib/libsys/aio_error.2 new file mode 100644 index 000000000000..69eb7cd90ee2 --- /dev/null +++ b/lib/libsys/aio_error.2 @@ -0,0 +1,103 @@ +.\" Copyright (c) 1999 Softweyr LLC. +.\" All rights reserved. +.\" +.\" 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 Softweyr LLC 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 Softweyr LLC 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. +.\" +.Dd January 2, 2021 +.Dt AIO_ERROR 2 +.Os +.Sh NAME +.Nm aio_error +.Nd retrieve error status of asynchronous I/O operation (REALTIME) +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In aio.h +.Ft int +.Fn aio_error "const struct aiocb *iocb" +.Sh DESCRIPTION +The +.Fn aio_error +system call returns the error status of the asynchronous I/O request +associated with the structure pointed to by +.Fa iocb . +.Sh RETURN VALUES +If the asynchronous I/O request has completed successfully, +.Fn aio_error +returns 0. +If the request has not yet completed, +.Er EINPROGRESS +is returned. +If the request has completed unsuccessfully the error +status is returned as described in +.Xr read 2 , +.Xr readv 2 , +.Xr write 2 , +.Xr writev 2 , +or +.Xr fsync 2 . +On failure, +.Fn aio_error +returns +.Dv -1 +and sets +.Dv errno +to indicate the error condition. +.Sh ERRORS +The +.Fn aio_error +system call will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa iocb +argument +does not reference an outstanding asynchronous I/O request. +.El +.Sh SEE ALSO +.Xr aio_cancel 2 , +.Xr aio_read 2 , +.Xr aio_readv 2 , +.Xr aio_return 2 , +.Xr aio_suspend 2 , +.Xr aio_write 2 , +.Xr aio_writev 2 , +.Xr fsync 2 , +.Xr read 2 , +.Xr write 2 , +.Xr aio 4 +.Sh STANDARDS +The +.Fn aio_error +system call +is expected to conform to the +.St -p1003.1 +standard. +.Sh HISTORY +The +.Fn aio_error +system call first appeared in +.Fx 3.0 . +.Sh AUTHORS +This +manual page was written by +.An Wes Peters Aq Mt wes@softweyr.com . diff --git a/lib/libsys/aio_fsync.2 b/lib/libsys/aio_fsync.2 new file mode 100644 index 000000000000..46fc5d95bcfd --- /dev/null +++ b/lib/libsys/aio_fsync.2 @@ -0,0 +1,181 @@ +.\" Copyright (c) 2013 Sergey Kandaurov +.\" All rights reserved. +.\" +.\" 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. +.\" +.Dd November 15, 2023 +.Dt AIO_FSYNC 2 +.Os +.Sh NAME +.Nm aio_fsync +.Nd asynchronous file synchronization (REALTIME) +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In aio.h +.Ft int +.Fn aio_fsync "int op" "struct aiocb *iocb" +.Sh DESCRIPTION +The +.Fn aio_fsync +system call allows the calling process to move all modified data +associated with the descriptor +.Fa iocb->aio_fildes +to a permanent storage device. +The call returns immediately after the synchronization request has been +enqueued to the descriptor; the synchronization may or may not have +completed at the time the call returns. +.Pp +The +.Fa op +argument can be set to +.Dv O_SYNC +to cause all currently queued I/O operations to be completed +as if by a call to +.Xr fsync 2 , +or +.Dv O_DSYNC +for the behavior of +.Xr fdatasync 2 . +.Pp +The +.Fa iocb +pointer may be subsequently used as an argument to +.Fn aio_return +and +.Fn aio_error +in order to determine return or error status for the enqueued operation +while it is in progress. +.Pp +If the request could not be enqueued (generally due to invalid arguments), +the call returns without having enqueued the request. +.Pp +The +.Fa iocb->aio_sigevent +structure can be used to request notification of the operation's +completion as described in +.Xr aio 4 . +.Sh RESTRICTIONS +The Asynchronous I/O Control Block structure pointed to by +.Fa iocb +must remain valid until the +operation has completed. +.Pp +The asynchronous I/O control buffer +.Fa iocb +should be zeroed before the +.Fn aio_fsync +call to avoid passing bogus context information to the kernel. +.Pp +Modification of the Asynchronous I/O Control Block structure is not allowed +while the request is queued. +.Sh RETURN VALUES +.Rv -std aio_fsync +.Sh ERRORS +The +.Fn aio_fsync +system call will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The request was not queued because of system resource limitations. +.It Bq Er EINVAL +The asynchronous notification method in +.Fa iocb->aio_sigevent.sigev_notify +is invalid or not supported. +.It Bq Er EOPNOTSUPP +Asynchronous file synchronization operations on the file descriptor +.Fa iocb->aio_fildes +are unsafe and unsafe asynchronous I/O operations are disabled. +.It Bq Er EINVAL +A value of the +.Fa op +argument is not set to +.Dv O_SYNC +or +.Dv O_DSYNC . +.El +.Pp +The following conditions may be synchronously detected when the +.Fn aio_fsync +system call is made, or asynchronously, at any time thereafter. +If they are detected at call time, +.Fn aio_fsync +returns -1 and sets +.Va errno +appropriately; otherwise the +.Fn aio_return +system call must be called, and will return -1, and +.Fn aio_error +must be called to determine the actual value that would have been +returned in +.Va errno . +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa iocb->aio_fildes +argument +is not a valid descriptor. +.It Bq Er EINVAL +This implementation does not support synchronized I/O for this file. +.El +.Pp +If the request is successfully enqueued, but subsequently cancelled +or an error occurs, the value returned by the +.Fn aio_return +system call is per the +.Xr read 2 +and +.Xr write 2 +system calls, and the value returned by the +.Fn aio_error +system call is one of the error returns from the +.Xr read 2 +or +.Xr write 2 +system calls. +.Sh SEE ALSO +.Xr aio_cancel 2 , +.Xr aio_error 2 , +.Xr aio_read 2 , +.Xr aio_return 2 , +.Xr aio_suspend 2 , +.Xr aio_waitcomplete 2 , +.Xr aio_write 2 , +.Xr fsync 2 , +.Xr sigevent 3 , +.Xr siginfo 3 , +.Xr aio 4 +.Sh STANDARDS +The +.Fn aio_fsync +system call is expected to conform to the +.St -p1003.1 +standard. +.Sh HISTORY +The +.Fn aio_fsync +system call first appeared in +.Fx 7.0 . +The +.Dv O_DSYNC +option appeared in +.Fx 13.0 . diff --git a/lib/libsys/aio_mlock.2 b/lib/libsys/aio_mlock.2 new file mode 100644 index 000000000000..02d54304c631 --- /dev/null +++ b/lib/libsys/aio_mlock.2 @@ -0,0 +1,136 @@ +.\" Copyright (c) 2013 Gleb Smirnoff <glebius@FreeBSD.org> +.\" All rights reserved. +.\" +.\" 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. +.\" +.Dd August 19, 2016 +.Dt AIO_MLOCK 2 +.Os +.Sh NAME +.Nm aio_mlock +.Nd asynchronous +.Xr mlock 2 +operation +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In aio.h +.Ft int +.Fn aio_mlock "struct aiocb *iocb" +.Sh DESCRIPTION +The +.Fn aio_mlock +system call allows the calling process to lock into memory the +physical pages associated with the virtual address range starting at +.Fa iocb->aio_buf +for +.Fa iocb->aio_nbytes +bytes. +The call returns immediately after the locking request has +been enqueued; the operation may or may not have completed at the time +the call returns. +.Pp +The +.Fa iocb +pointer may be subsequently used as an argument to +.Fn aio_return +and +.Fn aio_error +in order to determine return or error status for the enqueued operation +while it is in progress. +.Pp +If the request could not be enqueued (generally due to +.Xr aio 4 +limits), +then the call returns without having enqueued the request. +.Pp +The +.Fa iocb->aio_sigevent +structure can be used to request notification of the operation's +completion as described in +.Xr aio 4 . +.Sh RESTRICTIONS +The Asynchronous I/O Control Block structure pointed to by +.Fa iocb +and the buffer that the +.Fa iocb->aio_buf +member of that structure references must remain valid until the +operation has completed. +.Pp +The asynchronous I/O control buffer +.Fa iocb +should be zeroed before the +.Fn aio_mlock +call to avoid passing bogus context information to the kernel. +.Pp +Modifications of the Asynchronous I/O Control Block structure or the +memory mapping described by the virtual address range are not allowed +while the request is queued. +.Sh RETURN VALUES +.Rv -std aio_mlock +.Sh ERRORS +The +.Fn aio_mlock +system call will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The request was not queued because of system resource limitations. +.It Bq Er EINVAL +The asynchronous notification method in +.Fa iocb->aio_sigevent.sigev_notify +is invalid or not supported. +.El +.Pp +If the request is successfully enqueued, but subsequently cancelled +or an error occurs, the value returned by the +.Fn aio_return +system call is per the +.Xr mlock 2 +system call, and the value returned by the +.Fn aio_error +system call is one of the error returns from the +.Xr mlock 2 +system call, or +.Er ECANCELED +if the request was explicitly cancelled via a call to +.Fn aio_cancel . +.Sh SEE ALSO +.Xr aio_cancel 2 , +.Xr aio_error 2 , +.Xr aio_return 2 , +.Xr mlock 2 , +.Xr sigevent 3 , +.Xr aio 4 +.Sh PORTABILITY +The +.Fn aio_mlock +system call is a +.Fx +extension, and should not be used in portable code. +.Sh HISTORY +The +.Fn aio_mlock +system call first appeared in +.Fx 10.0 . +.Sh AUTHORS +The system call was introduced by +.An Gleb Smirnoff Aq Mt glebius@FreeBSD.org . diff --git a/lib/libsys/aio_read.2 b/lib/libsys/aio_read.2 new file mode 100644 index 000000000000..45779fff94c4 --- /dev/null +++ b/lib/libsys/aio_read.2 @@ -0,0 +1,290 @@ +.\" Copyright (c) 1998 Terry Lambert +.\" All rights reserved. +.\" +.\" 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. +.\" +.Dd March 27, 2025 +.Dt AIO_READ 2 +.Os +.Sh NAME +.Nm aio_read , +.Nm aio_read2 , +.Nm aio_readv +.Nd asynchronous read from a file (REALTIME) +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In aio.h +.Ft int +.Fn aio_read "struct aiocb *iocb" +.Ft int +.Fn aio_read2 "struct aiocb *iocb" "int flags" +.In sys/uio.h +.Ft int +.Fn aio_readv "struct aiocb *iocb" +.Sh DESCRIPTION +The +.Fn aio_read , +.Fn aio_read2 +and +.Fn aio_readv +system calls allow the calling process to read +from the descriptor +.Fa iocb->aio_fildes . +The syscalls return immediately after the read request has +been enqueued to the descriptor; the read may or may not have +completed at the time the call returns. +.Pp +For the +.Fn aio_read +and +.Fn aio_readv +calls, the read begins at the offset +.Fa iocb->aio_offset . +.Pp +The +.Fn aio_read +call will read +.Fa iocb->aio_nbytes +into the buffer pointed to by +.Fa iocb->aio_buf , +whereas +.Fn aio_readv +reads the data into the +.Fa iocb->aio_iovcnt +buffers specified by the members of the +.Fa iocb->aio_iov +array. +For +.Fn aio_readv +the +.Fa iovec +structure is defined in +.Xr readv 2 . +.Pp +The +.Fn aio_read2 +call takes the +.Fa flags +argument. +If +.Fa flags +is passed as zero, the call behaves identically to +.Fn aio_read . +The following flags can be specified by logical or: +.Bl -tag -width AIO_OP2_VECTORED +.It AIO_OP2_FOFFSET +The read occurs at the file descriptor offset, +which is advanced by the operation as done by the +.Xr read 2 +syscall. +The +.Fa iocb->aio_offset +field is ignored. +.It AIO_OP2_VECTORED +Similar to +.Fn aio_readv , +the read buffers are specified by the +.Fa aiocb->aio_iov +array. +.El +.Pp +The +.Fa iocb +pointer may be subsequently used as an argument to +.Fn aio_return +and +.Fn aio_error +in order to determine return or error status for the enqueued operation +while it is in progress. +.Pp +If the request could not be enqueued (generally due to invalid arguments), +then the call returns without having enqueued the request. +.Pp +If the request is successfully enqueued, the value of +.Fa iocb->aio_offset +can be modified during the request as context, so this value must +not be referenced after the request is enqueued. +.Pp +The +.Fa iocb->aio_sigevent +structure can be used to request notification of the operation's +completion as described in +.Xr aio 4 . +.Sh RESTRICTIONS +The Asynchronous I/O Control Block structure pointed to by +.Fa iocb +and the buffer that the +.Fa iocb->aio_buf +member of that structure references must remain valid until the +operation has completed. +.Pp +The asynchronous I/O control buffer +.Fa iocb +should be zeroed before the system +calls to avoid passing bogus context information to the kernel. +.Pp +Modifications of the Asynchronous I/O Control Block structure or the +buffer contents are not allowed while the request is queued. +.Pp +If the file offset in +.Fa iocb->aio_offset +is past the offset maximum for +.Fa iocb->aio_fildes , +no I/O will occur. +.Sh RETURN VALUES +.Rv -std aio_read aio_read2 aio_readv +.Sh DIAGNOSTICS +None. +.Sh ERRORS +The +.Fn aio_read , +.Fn aio_read2 , +and +.Fn aio_readv +system calls will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The request was not queued because of system resource limitations. +.It Bq Er EFAULT +Part of +.Fa aio_iov +points outside the process's allocated address space. +.It Bq Er EINVAL +The asynchronous notification method in +.Fa iocb->aio_sigevent.sigev_notify +is invalid or not supported. +.It Bq Er EOPNOTSUPP +Asynchronous read operations on the file descriptor +.Fa iocb->aio_fildes +are unsafe and unsafe asynchronous I/O operations are disabled. +.El +.Pp +The following conditions may be synchronously detected when the +.Fn aio_read +or +.Fn aio_readv +system call is made, or asynchronously, at any time thereafter. +If they +are detected at call time, +The calls return -1 and set +.Va errno +appropriately; otherwise the +.Fn aio_return +system call must be called, and will return -1, and +.Fn aio_error +must be called to determine the actual value that would have been +returned in +.Va errno . +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa iocb->aio_fildes +argument +is invalid. +.It Bq Er EINVAL +The offset +.Fa iocb->aio_offset +is not valid, the priority specified by +.Fa iocb->aio_reqprio +is not a valid priority, or the number of bytes specified by +.Fa iocb->aio_nbytes +is not valid. +.It Bq Er EOVERFLOW +The file is a regular file, +.Fa iocb->aio_nbytes +is greater than zero, the starting offset in +.Fa iocb->aio_offset +is before the end of the file, but is at or beyond the +.Fa iocb->aio_fildes +offset maximum. +.El +.Pp +If the request is successfully enqueued, but subsequently cancelled +or an error occurs, the value returned by the +.Fn aio_return +system call is per the +.Xr read 2 +system call, and the value returned by the +.Fn aio_error +system call is either one of the error returns from the +.Xr read 2 +system call, or one of: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa iocb->aio_fildes +argument +is invalid for reading. +.It Bq Er ECANCELED +The request was explicitly cancelled via a call to +.Fn aio_cancel . +.It Bq Er EINVAL +The offset +.Fa iocb->aio_offset +would be invalid. +.El +.Sh SEE ALSO +.Xr aio_cancel 2 , +.Xr aio_error 2 , +.Xr aio_return 2 , +.Xr aio_suspend 2 , +.Xr aio_waitcomplete 2 , +.Xr aio_write 2 , +.Xr sigevent 3 , +.Xr siginfo 3 , +.Xr aio 4 +.Sh STANDARDS +The +.Fn aio_read +system call is expected to conform to the +.St -p1003.1 +standard. +The +.Fn aio_read2 +and +.Fn aio_readv +system calls are +.Fx +extensions, +and should not be used in portable code. +.Sh HISTORY +The +.Fn aio_read +system call first appeared in +.Fx 3.0 . +The +.Fn aio_readv +system call first appeared in +.Fx 13.0 . +The +.Fn aio_read2 +system call first appeared in +.Fx 14.1 . +.Sh AUTHORS +This +manual page was written by +.An Terry Lambert Aq Mt terry@whistle.com . +.Sh BUGS +Invalid information in +.Fa iocb->_aiocb_private +may confuse the kernel. diff --git a/lib/libsys/aio_return.2 b/lib/libsys/aio_return.2 new file mode 100644 index 000000000000..499b85ef20d8 --- /dev/null +++ b/lib/libsys/aio_return.2 @@ -0,0 +1,108 @@ +.\" Copyright (c) 1999 Softweyr LLC. +.\" All rights reserved. +.\" +.\" 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 Softweyr LLC 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 Softweyr LLC 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. +.\" +.Dd January 11, 2021 +.Dt AIO_RETURN 2 +.Os +.Sh NAME +.Nm aio_return +.Nd retrieve return status of asynchronous I/O operation (REALTIME) +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In aio.h +.Ft ssize_t +.Fn aio_return "struct aiocb *iocb" +.Sh DESCRIPTION +The +.Fn aio_return +system call returns the final status of the asynchronous I/O request +associated with the structure pointed to by +.Fa iocb . +.Pp +The +.Fn aio_return +system call +should only be called once, to obtain the final status of an asynchronous +I/O operation once it has completed +.Xr ( aio_error 2 +returns something other than +.Er EINPROGRESS ) . +.Sh RETURN VALUES +If the asynchronous I/O request has completed, the status is returned +as described in +.Xr read 2 , +.Xr readv 2 , +.Xr write 2 , +.Xr writev 2 , +or +.Xr fsync 2 . +Otherwise, +.Fn aio_return +returns \-1 and sets +.Va errno +to indicate the error condition. +.Sh ERRORS +The +.Fn aio_return +system call will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa iocb +argument +does not reference a completed asynchronous I/O request. +.It Bq Er EINVAL +The I/O operation was submitted with +.Fn lio_listio , +and the value of the +.Fa aio_lio_opcode +is invalid. +.El +.Sh SEE ALSO +.Xr aio_cancel 2 , +.Xr aio_error 2 , +.Xr aio_suspend 2 , +.Xr aio_waitcomplete 2 , +.Xr aio_write 2 , +.Xr fsync 2 , +.Xr read 2 , +.Xr write 2 , +.Xr aio 4 +.Sh STANDARDS +The +.Fn aio_return +system call +is expected to conform to the +.St -p1003.1 +standard. +.Sh HISTORY +The +.Fn aio_return +system call first appeared in +.Fx 3.0 . +.Sh AUTHORS +This +manual page was written by +.An Wes Peters Aq Mt wes@softweyr.com . diff --git a/lib/libsys/aio_suspend.2 b/lib/libsys/aio_suspend.2 new file mode 100644 index 000000000000..c46b0292c34e --- /dev/null +++ b/lib/libsys/aio_suspend.2 @@ -0,0 +1,115 @@ +.\" Copyright (c) 1999 Softweyr LLC. +.\" All rights reserved. +.\" +.\" 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 Softweyr LLC 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 Softweyr LLC 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. +.\" +.Dd October 23, 2017 +.Dt AIO_SUSPEND 2 +.Os +.Sh NAME +.Nm aio_suspend +.Nd suspend until asynchronous I/O operations or timeout complete (REALTIME) +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In aio.h +.Ft int +.Fn aio_suspend "const struct aiocb *const iocbs[]" "int niocb" "const struct timespec *timeout" +.Sh DESCRIPTION +The +.Fn aio_suspend +system call suspends the calling process until at least one of the +specified asynchronous I/O requests have completed, a signal is +delivered, or the +.Fa timeout +has passed. +.Pp +The +.Fa iocbs +argument +is an array of +.Fa niocb +pointers to asynchronous I/O requests. +Array members containing +null pointers will be silently ignored. +.Pp +If +.Fa timeout +is not a null pointer, it specifies a maximum interval to suspend. +If +.Fa timeout +is a null pointer, the suspend blocks indefinitely. +To effect a +poll, the +.Fa timeout +should point to a zero-value timespec structure. +.Sh RETURN VALUES +If one or more of the specified asynchronous I/O requests have +completed, +.Fn aio_suspend +returns 0. +Otherwise it returns -1 and sets +.Va errno +to indicate the error, as enumerated below. +.Sh ERRORS +The +.Fn aio_suspend +system call will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +the +.Fa timeout +expired before any I/O requests completed. +.It Bq Er EINVAL +The +.Fa iocbs +argument +contains more asynchronous I/O requests than the +.Va vfs.aio.max_aio_queue_per_proc +.Xr sysctl 8 +variable, or at least one of the requests is not valid. +.It Bq Er EINTR +the suspend was interrupted by a signal. +.El +.Sh SEE ALSO +.Xr aio_cancel 2 , +.Xr aio_error 2 , +.Xr aio_return 2 , +.Xr aio_waitcomplete 2 , +.Xr aio_write 2 , +.Xr aio 4 +.Sh STANDARDS +The +.Fn aio_suspend +system call +is expected to conform to the +.St -p1003.1 +standard. +.Sh HISTORY +The +.Fn aio_suspend +system call first appeared in +.Fx 3.0 . +.Sh AUTHORS +This +manual page was written by +.An Wes Peters Aq Mt wes@softweyr.com . diff --git a/lib/libsys/aio_waitcomplete.2 b/lib/libsys/aio_waitcomplete.2 new file mode 100644 index 000000000000..e7f993e0b796 --- /dev/null +++ b/lib/libsys/aio_waitcomplete.2 @@ -0,0 +1,135 @@ +.\" Copyright (c) 1999 Christopher M Sedore. +.\" All rights reserved. +.\" +.\" 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 ``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. +.\" +.Dd March 27, 2025 +.Dt AIO_WAITCOMPLETE 2 +.Os +.Sh NAME +.Nm aio_waitcomplete +.Nd wait for the next completion of an aio request +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In aio.h +.Ft ssize_t +.Fn aio_waitcomplete "struct aiocb **iocbp" "struct timespec *timeout" +.Sh DESCRIPTION +The +.Fn aio_waitcomplete +system call waits for completion of an asynchronous I/O request. +Upon completion, +.Fn aio_waitcomplete +returns the result of the function and sets +.Fa iocbp +to point to the structure associated with the original request. +If an asynchronous I/O request is completed before +.Fn aio_waitcomplete +is called, it returns immediately with the completed request. +.Pp +If +.Fa timeout +is a non-NULL pointer, it specifies a maximum interval to wait for a +asynchronous I/O request to complete. +If +.Fa timeout +is a NULL pointer, +.Fn aio_waitcomplete +waits indefinitely. +To effect a poll, the +.Fa timeout +argument should be non-NULL, pointing to a zero-valued timeval structure. +.Pp +The +.Fn aio_waitcomplete +system call also serves the function of +.Fn aio_return , +thus +.Fn aio_return +should not be called for the control block returned in +.Fa iocbp . +.Sh RETURN VALUES +If an asynchronous I/O request has completed, +.Fa iocbp +is set to point to the control block passed with the original request, +and the status is returned as described in +.Xr read 2 , +.Xr write 2 , +or +.Xr fsync 2 . +On failure, +.Fn aio_waitcomplete +returns +.Dv -1 , +sets iocbp to +.Dv NULL +and sets +.Va errno +to indicate the error condition. +.Sh ERRORS +The +.Fn aio_waitcomplete +system call fails if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The process has not yet called +.Fn aio_read +or +.Fn aio_write . +.It Bq Er EINTR +A signal was delivered before the timeout expired and before any +asynchronous I/O requests completed. +.It Bq Er EINVAL +The specified time limit is invalid. +.It Bq Er EWOULDBLOCK +.It Bq Er EINPROGRESS +The specified time limit expired before any asynchronous I/O requests +completed. +.El +.Sh SEE ALSO +.Xr aio_cancel 2 , +.Xr aio_error 2 , +.Xr aio_read 2 , +.Xr aio_return 2 , +.Xr aio_suspend 2 , +.Xr aio_write 2 , +.Xr fsync 2 , +.Xr read 2 , +.Xr write 2 , +.Xr aio 4 +.Sh STANDARDS +The +.Fn aio_waitcomplete +system call is a +.Fx Ns -specific +extension. +.Sh HISTORY +The +.Fn aio_waitcomplete +system call first appeared in +.Fx 4.0 . +.Sh AUTHORS +The +.Fn aio_waitcomplete +system call and this manual page were written by +.An Christopher M Sedore Aq Mt cmsedore@maxwell.syr.edu . diff --git a/lib/libsys/aio_write.2 b/lib/libsys/aio_write.2 new file mode 100644 index 000000000000..107e347ac335 --- /dev/null +++ b/lib/libsys/aio_write.2 @@ -0,0 +1,291 @@ +.\" Copyright (c) 1999 Softweyr LLC. +.\" All rights reserved. +.\" +.\" 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 Softweyr LLC 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 Softweyr LLC 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. +.\" +.Dd March 27, 2025 +.Dt AIO_WRITE 2 +.Os +.Sh NAME +.Nm aio_write , +.Nm aio_write2 , +.Nm aio_writev +.Nd asynchronous write to a file (REALTIME) +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In aio.h +.Ft int +.Fn aio_write "struct aiocb *iocb" +.Ft int +.Fn aio_write2 "struct aiocb *iocb" "int flags" +.In sys/uio.h +.Ft int +.Fn aio_writev "struct aiocb *iocb" +.Sh DESCRIPTION +The +.Fn aio_write , +.Fn aio_write2 , +and +.Fn aio_writev +system calls allow the calling process to write +to the descriptor +.Fa iocb->aio_fildes . +The syscalls return immediately after the write request has been enqueued +to the descriptor; the write may or may not have completed at the time +the call returns. +.Pp +The +.Fn aio_write +call will write +.Fa iocb->aio_nbytes +from the buffer pointed to by +.Fa iocb->aio_buf , +whereas +.Fn aio_writev +gathers the data from the +.Fa iocb->aio_iovcnt +buffers specified by the members of the +.Fa iocb->aio_iov +array. +.Pp +If the request could not be enqueued, generally due +to invalid arguments, the call returns without having enqueued the +request. +.Pp +For +.Fn aio_writev +the +.Fa iovec +structure is defined in +.Xr writev 2 . +.Pp +If +.Dv O_APPEND +is set for +.Fa iocb->aio_fildes , +write operations append to the file in the same order as the calls were +made. +If +.Dv O_APPEND +is not set for the file descriptor, the write operation for +.Fn aio_write +will occur at +the absolute position from the beginning of the file plus +.Fa iocb->aio_offset . +.Pp +The +.Fn aio_write2 +call takes the +.Fa flags +argument. +If +.Fa flags +is passed as zero, the call behaves identically to +.Fn aio_write . +The following flags can be specified by logical or: +.Bl -tag -width AIO_OP2_VECTORED +.It AIO_OP2_FOFFSET +The write for non +.Dv O_APPEND +file descriptors occurs at the file descriptor offset, +which is advanced by the operation as done by the +.Xr write 2 +syscall. +The +.Fa iocb->aio_offset +field is ignored. +.It AIO_OP2_VECTORED +Similar to +.Fn aio_writev , +the write buffers are specified by the +.Fa aiocb->aio_iov +array. +.El +.Pp +The +.Fa iocb +pointer may be subsequently used as an argument to +.Fn aio_return +and +.Fn aio_error +in order to determine return or error status for the enqueued operation +while it is in progress. +.Pp +If the request is successfully enqueued, the value of +.Fa iocb->aio_offset +can be modified during the request as context, so this value must not +be referenced after the request is enqueued. +.Pp +The +.Fa iocb->aio_sigevent +structure can be used to request notification of the operation's +completion as described in +.Xr aio 4 . +.Sh RESTRICTIONS +The Asynchronous I/O Control Block structure pointed to by +.Fa iocb +and the buffer that the +.Fa iocb->aio_buf +member of that structure references must remain valid until the +operation has completed. +.Pp +The asynchronous I/O control buffer +.Fa iocb +should be zeroed before the +system calls to avoid passing bogus context information to the kernel. +.Pp +Modifications of the Asynchronous I/O Control Block structure or the +buffer contents are not allowed while the request is queued. +.Pp +If the file offset in +.Fa iocb->aio_offset +is past the offset maximum for +.Fa iocb->aio_fildes , +no I/O will occur. +.Sh RETURN VALUES +.Rv -std aio_write aio_writev +.Sh ERRORS +The +.Fn aio_write , +.Fn aio_write2 , +and +.Fn aio_writev +system calls will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The request was not queued because of system resource limitations. +.It Bq Er EFAULT +Part of +.Fa aio_iov +points outside the process's allocated address space. +.It Bq Er EINVAL +The asynchronous notification method in +.Fa iocb->aio_sigevent.sigev_notify +is invalid or not supported. +.It Bq Er EOPNOTSUPP +Asynchronous write operations on the file descriptor +.Fa iocb->aio_fildes +are unsafe and unsafe asynchronous I/O operations are disabled. +.El +.Pp +The following conditions may be synchronously detected when the +.Fn aio_write , +.Fn aio_write2 , +or +.Fn aio_writev +system call is made, or asynchronously, at any time thereafter. +If they +are detected at call time, the calls return -1 and set +.Va errno +appropriately; otherwise the +.Fn aio_return +system call must be called, and will return -1, and +.Fn aio_error +must be called to determine the actual value that would have been +returned in +.Va errno . +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa iocb->aio_fildes +argument +is invalid, or is not opened for writing. +.It Bq Er EINVAL +The offset +.Fa iocb->aio_offset +is not valid, the priority specified by +.Fa iocb->aio_reqprio +is not a valid priority, or the number of bytes specified by +.Fa iocb->aio_nbytes +is not valid. +.El +.Pp +If the request is successfully enqueued, but subsequently canceled +or an error occurs, the value returned by the +.Fn aio_return +system call is per the +.Xr write 2 +system call, and the value returned by the +.Fn aio_error +system call is either one of the error returns from the +.Xr write 2 +system call, or one of: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa iocb->aio_fildes +argument +is invalid for writing. +.It Bq Er ECANCELED +The request was explicitly canceled via a call to +.Fn aio_cancel . +.It Bq Er EINVAL +The offset +.Fa iocb->aio_offset +would be invalid. +.El +.Sh SEE ALSO +.Xr aio_cancel 2 , +.Xr aio_error 2 , +.Xr aio_return 2 , +.Xr aio_suspend 2 , +.Xr aio_waitcomplete 2 , +.Xr sigevent 3 , +.Xr siginfo 3 , +.Xr aio 4 +.Sh STANDARDS +The +.Fn aio_write +system call +is expected to conform to the +.St -p1003.1 +standard. +.Pp +The +.Fn aio_write2 +and +.Fn aio_writev +system calls are +.Fx +extensions, +and should not be used in portable code. +.Sh HISTORY +The +.Fn aio_write +system call first appeared in +.Fx 3.0 . +The +.Fn aio_writev +system call first appeared in +.Fx 13.0 . +The +.Fn aio_write2 +system call first appeared in +.Fx 14.1 . +.Sh AUTHORS +This manual page was written by +.An Wes Peters Aq Mt wes@softweyr.com . +.Sh BUGS +Invalid information in +.Fa iocb->_aiocb_private +may confuse the kernel. diff --git a/lib/libsys/amd64/Makefile.sys b/lib/libsys/amd64/Makefile.sys new file mode 100644 index 000000000000..8134bdc422a6 --- /dev/null +++ b/lib/libsys/amd64/Makefile.sys @@ -0,0 +1,9 @@ +SRCS+= \ + amd64_get_fsbase.c \ + amd64_get_gsbase.c \ + amd64_set_fsbase.c \ + amd64_set_gsbase.c \ + amd64_set_tlsbase.c \ + rfork_thread.S + +MDASM= vfork.S cerror.S getcontext.S diff --git a/lib/libsys/amd64/Makefile.thr b/lib/libsys/amd64/Makefile.thr new file mode 100644 index 000000000000..52e861709faf --- /dev/null +++ b/lib/libsys/amd64/Makefile.thr @@ -0,0 +1 @@ +SRCS+= _umtx_op_err.S diff --git a/lib/libsys/amd64/SYS.h b/lib/libsys/amd64/SYS.h new file mode 100644 index 000000000000..e27bb2cf9a93 --- /dev/null +++ b/lib/libsys/amd64/SYS.h @@ -0,0 +1,59 @@ +/*- + * SPDX-License-Identifier: BSD-3-Clause + * + * Copyright (c) 1990 The Regents of the University of California. + * All rights reserved. + * + * This code is derived from software contributed to Berkeley by + * William Jolitz. + * + * 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. + * 3. Neither the name of the University nor the names of its contributors + * may be used to endorse or promote products derived from this software + * without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. + */ + +#include <sys/syscall.h> +#include <machine/asm.h> + +#define _SYSCALL(name) \ + mov $SYS_##name, %eax; \ + movq %rcx, %r10; \ + syscall + +#ifndef _SYSCALL_BODY +#define _SYSCALL_BODY(name) \ + _SYSCALL(name); \ + jb HIDENAME(cerror); \ + ret +#endif + +#define RSYSCALL(name) ENTRY(__sys_##name); \ + WEAK_REFERENCE(__sys_##name, name); \ + WEAK_REFERENCE(__sys_##name, _##name); \ + _SYSCALL_BODY(name); \ + END(__sys_##name) + +#define PSEUDO(name) ENTRY(__sys_##name); \ + WEAK_REFERENCE(__sys_##name, _##name); \ + _SYSCALL_BODY(name); \ + END(__sys_##name) diff --git a/lib/libsys/amd64/Symbol.sys.map b/lib/libsys/amd64/Symbol.sys.map new file mode 100644 index 000000000000..11e0507b6613 --- /dev/null +++ b/lib/libsys/amd64/Symbol.sys.map @@ -0,0 +1,22 @@ +FBSD_1.0 { + rfork_thread; + amd64_get_fsbase; + amd64_get_gsbase; + amd64_set_fsbase; + amd64_set_gsbase; +}; + +FBSD_1.6 { + x86_pkru_get_perm; + x86_pkru_set_perm; + x86_pkru_protect_range; + x86_pkru_unprotect_range; +}; + +FBSD_1.8 { + amd64_set_tlsbase; +}; + +FBSDprivate_1.0 { + _vfork; +}; diff --git a/lib/libsys/amd64/_umtx_op_err.S b/lib/libsys/amd64/_umtx_op_err.S new file mode 100644 index 000000000000..c5fb2f26d6f6 --- /dev/null +++ b/lib/libsys/amd64/_umtx_op_err.S @@ -0,0 +1,40 @@ +/*- + * Copyright (C) 2008 David Xu <davidxu@freebsd.org> + * All rights reserved. + * + * 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. Neither the name of the author nor the names of its contributors + * may be used to endorse or promote products derived from this software + * without specific prior written permission. + * + * 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. + */ + +#include <sys/syscall.h> +#include <machine/asm.h> + +#define RSYSCALL_ERR(x) ENTRY(__CONCAT(x, _err)); \ + mov __CONCAT($SYS_,x),%rax; \ + KERNCALL; \ + ret; \ + END(__CONCAT(x, _err)); + +#define KERNCALL movq %rcx, %r10; syscall + +RSYSCALL_ERR(_umtx_op) + + .section .note.GNU-stack,"",%progbits diff --git a/lib/libsys/amd64/amd64_get_fsbase.c b/lib/libsys/amd64/amd64_get_fsbase.c new file mode 100644 index 000000000000..00f16a5e404f --- /dev/null +++ b/lib/libsys/amd64/amd64_get_fsbase.c @@ -0,0 +1,63 @@ +/*- + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (c) 2003 Peter Wemm + * Copyright (c) 2017, 2018 The FreeBSD Foundation + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * 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. + */ + +#define _WANT_P_OSREL +#include <sys/param.h> +#include <machine/cpufunc.h> +#include <machine/specialreg.h> +#include <machine/sysarch.h> +#include <x86/ifunc.h> +#include "libc_private.h" + +static int +amd64_get_fsbase_cpu(void **addr) +{ + + *addr = (void *)rdfsbase(); + return (0); +} + +static int +amd64_get_fsbase_syscall(void **addr) +{ + + return (sysarch(AMD64_GET_FSBASE, addr)); +} + +DEFINE_UIFUNC(, int, amd64_get_fsbase, (void **)) +{ + + if (__getosreldate() >= P_OSREL_WRFSBASE && + (cpu_stdext_feature & CPUID_STDEXT_FSGSBASE) != 0) + return (amd64_get_fsbase_cpu); + return (amd64_get_fsbase_syscall); +} diff --git a/lib/libsys/amd64/amd64_get_gsbase.c b/lib/libsys/amd64/amd64_get_gsbase.c new file mode 100644 index 000000000000..ef135b1eed7f --- /dev/null +++ b/lib/libsys/amd64/amd64_get_gsbase.c @@ -0,0 +1,63 @@ +/*- + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (c) 2003 Peter Wemm + * Copyright (c) 2017, 2018 The FreeBSD Foundation + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * 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. + */ + +#define _WANT_P_OSREL +#include <sys/param.h> +#include <machine/cpufunc.h> +#include <machine/specialreg.h> +#include <machine/sysarch.h> +#include <x86/ifunc.h> +#include "libc_private.h" + +static int +amd64_get_gsbase_cpu(void **addr) +{ + + *addr = (void *)rdgsbase(); + return (0); +} + +static int +amd64_get_gsbase_syscall(void **addr) +{ + + return (sysarch(AMD64_GET_GSBASE, addr)); +} + +DEFINE_UIFUNC(, int, amd64_get_gsbase, (void **)) +{ + + if (__getosreldate() >= P_OSREL_WRFSBASE && + (cpu_stdext_feature & CPUID_STDEXT_FSGSBASE) != 0) + return (amd64_get_gsbase_cpu); + return (amd64_get_gsbase_syscall); +} diff --git a/lib/libsys/amd64/amd64_set_fsbase.c b/lib/libsys/amd64/amd64_set_fsbase.c new file mode 100644 index 000000000000..f1690fde6e17 --- /dev/null +++ b/lib/libsys/amd64/amd64_set_fsbase.c @@ -0,0 +1,63 @@ +/*- + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (c) 2003 Peter Wemm + * Copyright (c) 2017, 2018 The FreeBSD Foundation + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * 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. + */ + +#define _WANT_P_OSREL +#include <sys/param.h> +#include <machine/cpufunc.h> +#include <machine/specialreg.h> +#include <machine/sysarch.h> +#include <x86/ifunc.h> +#include "libc_private.h" + +static int +amd64_set_fsbase_cpu(void *addr) +{ + + wrfsbase((uintptr_t)addr); + return (0); +} + +static int +amd64_set_fsbase_syscall(void *addr) +{ + + return (sysarch(AMD64_SET_FSBASE, &addr)); +} + +DEFINE_UIFUNC(, int, amd64_set_fsbase, (void *)) +{ + + if (__getosreldate() >= P_OSREL_WRFSBASE && + (cpu_stdext_feature & CPUID_STDEXT_FSGSBASE) != 0) + return (amd64_set_fsbase_cpu); + return (amd64_set_fsbase_syscall); +} diff --git a/lib/libsys/amd64/amd64_set_gsbase.c b/lib/libsys/amd64/amd64_set_gsbase.c new file mode 100644 index 000000000000..756bbae18844 --- /dev/null +++ b/lib/libsys/amd64/amd64_set_gsbase.c @@ -0,0 +1,63 @@ +/*- + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (c) 2003 Peter Wemm + * Copyright (c) 2017, 2018 The FreeBSD Foundation + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * 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. + */ + +#define _WANT_P_OSREL +#include <sys/param.h> +#include <machine/cpufunc.h> +#include <machine/specialreg.h> +#include <machine/sysarch.h> +#include <x86/ifunc.h> +#include "libc_private.h" + +static int +amd64_set_gsbase_cpu(void *addr) +{ + + wrgsbase((uintptr_t)addr); + return (0); +} + +static int +amd64_set_gsbase_syscall(void *addr) +{ + + return (sysarch(AMD64_SET_GSBASE, &addr)); +} + +DEFINE_UIFUNC(, int, amd64_set_gsbase, (void *)) +{ + + if (__getosreldate() >= P_OSREL_WRFSBASE && + (cpu_stdext_feature & CPUID_STDEXT_FSGSBASE) != 0) + return (amd64_set_gsbase_cpu); + return (amd64_set_gsbase_syscall); +} diff --git a/lib/libsys/amd64/amd64_set_tlsbase.c b/lib/libsys/amd64/amd64_set_tlsbase.c new file mode 100644 index 000000000000..a28441fbfc5d --- /dev/null +++ b/lib/libsys/amd64/amd64_set_tlsbase.c @@ -0,0 +1,51 @@ +/*- + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (c) 2025 The FreeBSD Foundation + * All rights reserved. + * + * This software was developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * 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. + */ + +#define _WANT_P_OSREL +#include <sys/param.h> +#include <machine/cpufunc.h> +#include <machine/specialreg.h> +#include <machine/sysarch.h> +#include <x86/ifunc.h> +#include "libc_private.h" + +static int +amd64_set_tlsbase_syscall(void *addr) +{ + return (sysarch(AMD64_SET_TLSBASE, &addr)); +} + +DEFINE_UIFUNC(, int, amd64_set_tlsbase, (void *)) +{ + if (__getosreldate() >= P_OSREL_TLSBASE) + return (amd64_set_tlsbase_syscall); + return (amd64_set_fsbase); +} diff --git a/lib/libsys/amd64/cerror.S b/lib/libsys/amd64/cerror.S new file mode 100644 index 000000000000..68273a5c971f --- /dev/null +++ b/lib/libsys/amd64/cerror.S @@ -0,0 +1,55 @@ +/*- + * Copyright (c) 1990 The Regents of the University of California. + * All rights reserved. + * + * This code is derived from software contributed to Berkeley by + * William Jolitz. + * + * 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. + * 3. Neither the name of the University nor the names of its contributors + * may be used to endorse or promote products derived from this software + * without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. + */ + +#include <machine/asm.h> +#include "SYS.h" + + .globl HIDENAME(cerror) + .hidden HIDENAME(cerror) + + /* + * The __error() function is thread aware. For non-threaded + * programs and the initial thread in threaded programs, + * it returns a pointer to the global errno variable. + */ + .globl CNAME(__error) + .type CNAME(__error),@function +HIDENAME(cerror): + pushq %rax + call PIC_PLT(CNAME(__error)) + popq %rcx + movl %ecx,(%rax) + movq $-1,%rax + movq $-1,%rdx + ret + + .section .note.GNU-stack,"",%progbits diff --git a/lib/libsys/amd64/getcontext.S b/lib/libsys/amd64/getcontext.S new file mode 100644 index 000000000000..c3a856c879f8 --- /dev/null +++ b/lib/libsys/amd64/getcontext.S @@ -0,0 +1,45 @@ +/*- + * Copyright (c) 2003 Peter Wemm <peter@FreeBSD.org> + * All rights reserved. + * + * 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. + */ + +#include <machine/asm.h> +#include <SYS.h> + +/* + * This has to be magic to handle the multiple returns. + * Otherwise, the setcontext() syscall will return here and we'll + * pop off the return address and go to the *setcontext* call. + */ + WEAK_REFERENCE(__sys_getcontext, _getcontext) + WEAK_REFERENCE(__sys_getcontext, getcontext) +ENTRY(__sys_getcontext) + movq (%rsp),%rsi /* save getcontext return address */ + _SYSCALL(getcontext) + jb HIDENAME(cerror) + addq $8,%rsp /* remove stale (setcontext) return address */ + jmp *%rsi /* restore return address */ +END(__sys_getcontext) + + .section .note.GNU-stack,"",%progbits diff --git a/lib/libsys/amd64/rfork_thread.S b/lib/libsys/amd64/rfork_thread.S new file mode 100644 index 000000000000..a70551631f1b --- /dev/null +++ b/lib/libsys/amd64/rfork_thread.S @@ -0,0 +1,91 @@ +/*- + * Copyright (c) 2000 Peter Wemm <peter@FreeBSD.org> + * Copyright (c) 2003 Alan L. Cox <alc@cs.rice.edu> + * All rights reserved. + * + * 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. + */ + +#include <machine/asm.h> +/* + * With thanks to John Dyson for the original version of this. + */ + +#include <SYS.h> + +/* + * %edi %rsi %rdx %rcx + * rfork_thread(flags, stack_addr, start_fnc, start_arg); + * + * flags: Flags to rfork system call. See rfork(2). + * stack_addr: Top of stack for thread. + * start_fnc: Address of thread function to call in child. + * start_arg: Argument to pass to the thread function in child. + */ + +ENTRY(rfork_thread) + pushq %rbx + pushq %r12 + movq %rdx, %rbx + movq %rcx, %r12 + + /* + * Prepare and execute the thread creation syscall + */ + _SYSCALL(rfork) + jb 2f + + /* + * Check to see if we are in the parent or child + */ + cmpl $0, %edx + jnz 1f + popq %r12 + popq %rbx + ret + + /* + * If we are in the child (new thread), then + * set-up the call to the internal subroutine. If it + * returns, then call __exit. + */ +1: + movq %rsi, %rsp + movq %r12, %rdi + call *%rbx + movl %eax, %edi + + /* + * Exit system call + */ + _SYSCALL(exit) + + /* + * Branch here if the thread creation fails: + */ +2: + popq %r12 + popq %rbx + jmp HIDENAME(cerror) +END(rfork_thread) + + .section .note.GNU-stack,"",%progbits diff --git a/lib/libsys/amd64/vfork.S b/lib/libsys/amd64/vfork.S new file mode 100644 index 000000000000..e3c5f701dcff --- /dev/null +++ b/lib/libsys/amd64/vfork.S @@ -0,0 +1,48 @@ +/*- + * Copyright (c) 1990 The Regents of the University of California. + * All rights reserved. + * + * This code is derived from software contributed to Berkeley by + * William Jolitz. + * + * 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. + * 3. Neither the name of the University nor the names of its contributors + * may be used to endorse or promote products derived from this software + * without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. + */ + +#include <machine/asm.h> +#include "SYS.h" + + WEAK_REFERENCE(__sys_vfork, _vfork) + WEAK_REFERENCE(__sys_vfork, vfork) +ENTRY(__sys_vfork) + popq %rsi /* fetch return address (%rsi preserved) */ + _SYSCALL(vfork) + jb 1f + jmp *%rsi +1: + pushq %rsi + jmp HIDENAME(cerror) +END(__sys_vfork) + + .section .note.GNU-stack,"",%progbits diff --git a/lib/libsys/arm/Makefile.sys b/lib/libsys/arm/Makefile.sys new file mode 100644 index 000000000000..27d78978a2f4 --- /dev/null +++ b/lib/libsys/arm/Makefile.sys @@ -0,0 +1,6 @@ +SRCS+= __vdso_gettc.c \ + sched_getcpu_gen.c + +MDASM= \ + cerror.S \ + vfork.S diff --git a/lib/libsys/arm/SYS.h b/lib/libsys/arm/SYS.h new file mode 100644 index 000000000000..187851c67543 --- /dev/null +++ b/lib/libsys/arm/SYS.h @@ -0,0 +1,70 @@ +/* $NetBSD: SYS.h,v 1.8 2003/08/07 16:42:02 agc Exp $ */ + +/*- + * SPDX-License-Identifier: BSD-3-Clause + * + * Copyright (c) 1990 The Regents of the University of California. + * All rights reserved. + * + * This code is derived from software contributed to Berkeley by + * William Jolitz. + * + * 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. + * 3. Neither the name of the University nor the names of its contributors + * may be used to endorse or promote products derived from this software + * without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. + */ + +#include <machine/asm.h> +#include <sys/syscall.h> + +#define _SYSCALL(x) \ + mov ip, r7; \ + ldr r7, =SYS_ ## x; \ + swi 0; \ + mov r7, ip + +#define CERROR _C_LABEL(cerror) + +#ifndef _SYSCALL_BODY +#define _SYSCALL_BODY(x) \ + _SYSCALL(x); \ + it cs; \ + bcs PIC_SYM(CERROR, PLT); \ + RET +#endif + +#define PSEUDO(x) \ + ENTRY(__CONCAT(__sys_, x)); \ + .weak _C_LABEL(__CONCAT(_,x)); \ + .set _C_LABEL(__CONCAT(_,x)),_C_LABEL(__CONCAT(__sys_,x)); \ + _SYSCALL_BODY(x) + +#define RSYSCALL(x) \ + ENTRY(__CONCAT(__sys_, x)); \ + .weak _C_LABEL(x); \ + .set _C_LABEL(x), _C_LABEL(__CONCAT(__sys_,x)); \ + .weak _C_LABEL(__CONCAT(_,x)); \ + .set _C_LABEL(__CONCAT(_,x)),_C_LABEL(__CONCAT(__sys_,x)); \ + _SYSCALL_BODY(x); \ + + .globl CERROR diff --git a/lib/libsys/arm/Symbol.sys.map b/lib/libsys/arm/Symbol.sys.map new file mode 100644 index 000000000000..a9445ae7ba23 --- /dev/null +++ b/lib/libsys/arm/Symbol.sys.map @@ -0,0 +1,3 @@ +FBSDprivate_1.0 { + _vfork; +}; diff --git a/lib/libsys/arm/__vdso_gettc.c b/lib/libsys/arm/__vdso_gettc.c new file mode 100644 index 000000000000..cb4bdec1e8ef --- /dev/null +++ b/lib/libsys/arm/__vdso_gettc.c @@ -0,0 +1,81 @@ +/*- + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (c) 2015 The FreeBSD Foundation + * + * This software was developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * 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. + */ + +#include <sys/types.h> +#include <sys/elf.h> +#include <sys/time.h> +#include <sys/vdso.h> +#include <machine/cpufunc.h> +#include <machine/acle-compat.h> +#include <errno.h> +#include "libc_private.h" + +static inline uint64_t +cp15_cntvct_get(void) +{ + uint64_t reg; + + __asm __volatile("mrrc\tp15, 1, %Q0, %R0, c14" : "=r" (reg)); + return (reg); +} + +static inline uint64_t +cp15_cntpct_get(void) +{ + uint64_t reg; + + __asm __volatile("mrrc\tp15, 0, %Q0, %R0, c14" : "=r" (reg)); + return (reg); +} + +#pragma weak __vdso_gettc +int +__vdso_gettc(const struct vdso_timehands *th, u_int *tc) +{ + + if (th->th_algo != VDSO_TH_ALGO_ARM_GENTIM) + return (ENOSYS); + /* + * Userspace gettimeofday() is only enabled on ARMv7 CPUs, but + * libc is compiled for ARMv6. Due to clang issues, .arch + * armv7-a directive does not work. + */ + __asm __volatile(".word\t0xf57ff06f" : : : "memory"); /* isb */ + *tc = th->th_physical == 0 ? cp15_cntvct_get() : cp15_cntpct_get(); + return (0); +} + +#pragma weak __vdso_gettimekeep +int +__vdso_gettimekeep(struct vdso_timekeep **tk) +{ + + return (_elf_aux_info(AT_TIMEKEEP, tk, sizeof(*tk))); +} diff --git a/lib/libsys/arm/cerror.S b/lib/libsys/arm/cerror.S new file mode 100644 index 000000000000..7a9947fe7df3 --- /dev/null +++ b/lib/libsys/arm/cerror.S @@ -0,0 +1,48 @@ +/* $NetBSD: cerror.S,v 1.5 2003/08/07 16:42:04 agc Exp $ */ + +/*- + * Copyright (c) 1990 The Regents of the University of California. + * All rights reserved. + * + * 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. + * 3. Neither the name of the University nor the names of its contributors + * may be used to endorse or promote products derived from this software + * without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. + */ + +#include <machine/asm.h> +#include "SYS.h" + +.globl _C_LABEL(__error) +.type _C_LABEL(__error),%function + +ASENTRY(CERROR) + stmfd sp!, {r4, lr} + mov r4, r0 + bl PIC_SYM(_C_LABEL(__error), PLT) + str r4, [r0] + mvn r0, #0x00000000 + mvn r1, #0x00000000 + ldmfd sp!, {r4, pc} +END(CERROR) + + .section .note.GNU-stack,"",%progbits diff --git a/lib/libsys/arm/vfork.S b/lib/libsys/arm/vfork.S new file mode 100644 index 000000000000..ef9a426c6de5 --- /dev/null +++ b/lib/libsys/arm/vfork.S @@ -0,0 +1,58 @@ +/* $NetBSD: Ovfork.S,v 1.6 2003/08/07 16:42:03 agc Exp $ */ + +/*- + * Copyright (c) 1990 The Regents of the University of California. + * All rights reserved. + * + * 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. + * 3. Neither the name of the University nor the names of its contributors + * may be used to endorse or promote products derived from this software + * without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. + */ + +#include <machine/asm.h> +#include "SYS.h" + +/* + * pid = vfork(); + * + * On return from the SWI: + * r1 == 0 in parent process, r1 == 1 in child process. + * r0 == pid of child in parent, r0 == pid of parent in child. + */ + .text + .align 0 + +ENTRY(__sys_vfork) + .weak _C_LABEL(vfork); + .set _C_LABEL(vfork), _C_LABEL(__sys_vfork); + .weak _C_LABEL(_vfork); + .set _C_LABEL(_vfork), _C_LABEL(__sys_vfork); + mov r2, r14 + _SYSCALL(vfork) + bcs PIC_SYM(CERROR, PLT) + sub r1, r1, #1 /* r1 == 0xffffffff if parent, 0 if child */ + and r0, r0, r1 /* r0 == 0 if child, else unchanged */ + mov r15, r2 +END(__sys_vfork) + + .section .note.GNU-stack,"",%progbits diff --git a/lib/libsys/auxv.3 b/lib/libsys/auxv.3 new file mode 100644 index 000000000000..b3b741937ac7 --- /dev/null +++ b/lib/libsys/auxv.3 @@ -0,0 +1,111 @@ +.\" +.\" Copyright (c) 2019 Ian Lepore <ian@freebsd.org> +.\" +.\" 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 ``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 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. +.\" +.Dd June 24, 2025 +.Dt ELF_AUX_INFO 3 +.Os +.Sh NAME +.Nm elf_aux_info +.Nd extract data from the elf auxiliary vector of the current process +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/auxv.h +.Ft int +.Fn elf_aux_info "int aux" "void *buf" "int buflen" +.Sh DESCRIPTION +The +.Fn elf_aux_info +function retrieves the auxiliary info vector requested in +.Va aux . +The information is stored into the provided buffer if it will fit. +The following values, defined in +.In sys/elf_common.h +can be requested (corresponding buffer sizes are specified in parenthesis): +.Bl -tag -width AT_OSRELDATE +.It AT_CANARY +The canary value for SSP (arbitrary sized buffer, as many bytes are +returned as it fits into it, rest is zeroed). +.It AT_EXECPATH +The path of executed program +.Dv (MAXPATHLEN). +This may not be present if the process was initialized by +.Xr fexecve 2 +and the namecache no longer contains the file's name. +.It AT_HWCAP +CPU / hardware feature flags +.Dv (sizeof(u_long)). +.It AT_HWCAP2 +CPU / hardware feature flags +.Dv (sizeof(u_long)). +.It AT_HWCAP3 +CPU / hardware feature flags +.Dv (sizeof(u_long)). +.It AT_HWCAP4 +CPU / hardware feature flags +.Dv (sizeof(u_long)). +.It AT_NCPUS +Number of CPUs +.Dv (sizeof(int)). +.It AT_OSRELDATE +The +.Dv OSRELDATE +of the kernel or jail the program is running on +.Dv (sizeof(int)). +.It AT_PAGESIZES +Vector of page sizes (arbitrary sized buffer, as many elements of the +.Dv pagesizes +array are returned as it fits). +.It AT_PAGESZ +Page size in bytes +.Dv (sizeof(int)). +.It AT_TIMEKEEP +Pointer to VDSO timehands (for library internal use, +.Dv sizeof(void *)). +.It AT_USRSTACKBASE +Top of the user stack for main thread. +.It AT_USRSTACKLIM +Limit for grow of the user stack for main thread. +.El +.Sh RETURN VALUES +Returns zero on success, or an error number on failure. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINVAL +An unknown item was requested. +.It Bq Er EINVAL +The provided buffer was not the right size for the requested item. +.It Bq Er ENOENT +The requested item is not available. +.El +.Sh HISTORY +The +.Fn elf_aux_info +function appeared in +.Fx 12.0 . +.Sh BUGS +Only a small subset of available auxiliary info vector items are +accessible with this function. +Some items require a "right-sized" buffer while others just require a +"big enough" buffer. diff --git a/lib/libsys/auxv.c b/lib/libsys/auxv.c new file mode 100644 index 000000000000..80702c66ba22 --- /dev/null +++ b/lib/libsys/auxv.c @@ -0,0 +1,444 @@ +/*- + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright 2010, 2012 Konstantin Belousov <kib@FreeBSD.ORG>. + * All rights reserved. + * + * 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 ``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 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. + * + */ + +#include "namespace.h" +#include <elf.h> +#include <errno.h> +#include <link.h> +#include <pthread.h> +#include <stdbool.h> +#include <string.h> +#include <sys/auxv.h> +#include "un-namespace.h" +#include "libc_private.h" +#include <machine/atomic.h> + +extern int _DYNAMIC; +#pragma weak _DYNAMIC + +void *__elf_aux_vector; + +#ifndef PIC +static pthread_once_t aux_vector_once = PTHREAD_ONCE_INIT; + +static void +init_aux_vector_once(void) +{ + Elf_Addr *sp; + + sp = (Elf_Addr *)environ; + while (*sp++ != 0) + ; + __elf_aux_vector = (Elf_Auxinfo *)sp; +} + +void +__init_elf_aux_vector(void) +{ + + if (&_DYNAMIC != NULL) + return; + _once(&aux_vector_once, init_aux_vector_once); +} +#endif + +static int aux_once; +static int pagesize, osreldate, canary_len, ncpus, pagesizes_len, bsdflags; +static int hwcap_present, hwcap2_present, hwcap3_present, hwcap4_present; +static char *canary, *pagesizes, *execpath; +static void *ps_strings, *timekeep; +static u_long hwcap, hwcap2, hwcap3, hwcap4; +static void *fxrng_seed_version; +static u_long usrstackbase, usrstacklim; + +#ifdef __powerpc__ +static int powerpc_new_auxv_format = 0; +static void _init_aux_powerpc_fixup(void); +int _powerpc_elf_aux_info(int, void *, int); +#endif + +/* + * This function might be called and actual body executed more than + * once in multithreading environment. Due to this, it is and must + * continue to be idempotent. All stores are atomic (no store + * tearing), because we only assign to int/long/ptr. + */ +static void +init_aux(void) +{ + Elf_Auxinfo *aux; + + if (atomic_load_acq_int(&aux_once)) + return; + for (aux = __elf_aux_vector; aux->a_type != AT_NULL; aux++) { + switch (aux->a_type) { + case AT_BSDFLAGS: + bsdflags = aux->a_un.a_val; + break; + + case AT_CANARY: + canary = (char *)(aux->a_un.a_ptr); + break; + + case AT_CANARYLEN: + canary_len = aux->a_un.a_val; + break; + + case AT_EXECPATH: + execpath = (char *)(aux->a_un.a_ptr); + break; + + case AT_HWCAP: + hwcap_present = 1; + hwcap = (u_long)(aux->a_un.a_val); + break; + + case AT_HWCAP2: + hwcap2_present = 1; + hwcap2 = (u_long)(aux->a_un.a_val); + break; + + case AT_HWCAP3: + hwcap3_present = 1; + hwcap3 = (u_long)(aux->a_un.a_val); + break; + + case AT_HWCAP4: + hwcap4_present = 1; + hwcap4 = (u_long)(aux->a_un.a_val); + break; + + case AT_PAGESIZES: + pagesizes = (char *)(aux->a_un.a_ptr); + break; + + case AT_PAGESIZESLEN: + pagesizes_len = aux->a_un.a_val; + break; + + case AT_PAGESZ: + pagesize = aux->a_un.a_val; + break; + + case AT_OSRELDATE: + osreldate = aux->a_un.a_val; + break; + + case AT_NCPUS: + ncpus = aux->a_un.a_val; + break; + + case AT_TIMEKEEP: + timekeep = aux->a_un.a_ptr; + break; + + case AT_PS_STRINGS: + ps_strings = aux->a_un.a_ptr; + break; + + case AT_FXRNG: + fxrng_seed_version = aux->a_un.a_ptr; + break; + + case AT_USRSTACKBASE: + usrstackbase = aux->a_un.a_val; + break; + + case AT_USRSTACKLIM: + usrstacklim = aux->a_un.a_val; + break; +#ifdef __powerpc__ + /* + * Since AT_STACKPROT is always set, and the common + * value 23 is mutually exclusive with the legacy powerpc + * value 21, the existence of AT_STACKPROT proves we are + * on the common format. + */ + case AT_STACKPROT: /* 23 */ + powerpc_new_auxv_format = 1; + break; +#endif + } + } +#ifdef __powerpc__ + if (!powerpc_new_auxv_format) + _init_aux_powerpc_fixup(); +#endif + + atomic_store_rel_int(&aux_once, 1); +} + +#ifdef __powerpc__ +static void +_init_aux_powerpc_fixup(void) +{ + Elf_Auxinfo *aux; + + /* + * Before 1300070, PowerPC platforms had nonstandard numbering for + * the aux vector. When running old binaries, the kernel will pass + * the vector using the old numbering. Reload affected variables. + */ + for (aux = __elf_aux_vector; aux->a_type != AT_NULL; aux++) { + switch (aux->a_type) { + case AT_OLD_CANARY: + canary = (char *)(aux->a_un.a_ptr); + break; + case AT_OLD_CANARYLEN: + canary_len = aux->a_un.a_val; + break; + case AT_OLD_EXECPATH: + execpath = (char *)(aux->a_un.a_ptr); + break; + case AT_OLD_PAGESIZES: + pagesizes = (char *)(aux->a_un.a_ptr); + break; + case AT_OLD_PAGESIZESLEN: + pagesizes_len = aux->a_un.a_val; + break; + case AT_OLD_OSRELDATE: + osreldate = aux->a_un.a_val; + break; + case AT_OLD_NCPUS: + ncpus = aux->a_un.a_val; + break; + } + } +} + +int +_powerpc_elf_aux_info(int aux, void *buf, int buflen) +{ + + /* + * If we are in the old auxv format, we need to translate the aux + * parameter of elf_aux_info() calls into the common auxv format. + * Internal libc calls always use the common format, and they + * directly call _elf_aux_info instead of using the weak symbol. + */ + if (!powerpc_new_auxv_format) { + switch (aux) { + case AT_OLD_EXECPATH: + aux = AT_EXECPATH; + break; + case AT_OLD_CANARY: + aux = AT_CANARY; + break; + case AT_OLD_CANARYLEN: + aux = AT_CANARYLEN; + break; + case AT_OLD_OSRELDATE: + aux = AT_OSRELDATE; + break; + case AT_OLD_NCPUS: + aux = AT_NCPUS; + break; + case AT_OLD_PAGESIZES: + aux = AT_PAGESIZES; + break; + case AT_OLD_PAGESIZESLEN: + aux = AT_PAGESIZESLEN; + break; + case AT_OLD_STACKPROT: + aux = AT_STACKPROT; + break; + } + } + return _elf_aux_info(aux, buf, buflen); +} +__weak_reference(_powerpc_elf_aux_info, elf_aux_info); +#else +__weak_reference(_elf_aux_info, elf_aux_info); +#endif + +int +_elf_aux_info(int aux, void *buf, int buflen) +{ + int res; + +#ifndef PIC + __init_elf_aux_vector(); +#endif + if (__elf_aux_vector == NULL) + return (ENOSYS); + init_aux(); /* idempotent */ + + if (buflen < 0) + return (EINVAL); + + switch (aux) { + case AT_CANARY: + if (canary != NULL && canary_len >= buflen) { + memcpy(buf, canary, buflen); + memset(canary, 0, canary_len); + canary = NULL; + res = 0; + } else + res = ENOENT; + break; + case AT_EXECPATH: + if (execpath == NULL) + res = ENOENT; + else if (buf == NULL) + res = EINVAL; + else { + if (strlcpy(buf, execpath, buflen) >= + (unsigned int)buflen) + res = EINVAL; + else + res = 0; + } + break; + case AT_HWCAP: + if (hwcap_present && buflen == sizeof(u_long)) { + *(u_long *)buf = hwcap; + res = 0; + } else + res = ENOENT; + break; + case AT_HWCAP2: + if (hwcap2_present && buflen == sizeof(u_long)) { + *(u_long *)buf = hwcap2; + res = 0; + } else + res = ENOENT; + break; + case AT_HWCAP3: + if (hwcap3_present && buflen == sizeof(u_long)) { + *(u_long *)buf = hwcap3; + res = 0; + } else + res = ENOENT; + break; + case AT_HWCAP4: + if (hwcap4_present && buflen == sizeof(u_long)) { + *(u_long *)buf = hwcap4; + res = 0; + } else + res = ENOENT; + break; + case AT_PAGESIZES: + if (pagesizes != NULL && pagesizes_len >= buflen) { + memcpy(buf, pagesizes, buflen); + res = 0; + } else + res = ENOENT; + break; + case AT_PAGESZ: + if (buflen == sizeof(int)) { + if (pagesize != 0) { + *(int *)buf = pagesize; + res = 0; + } else + res = ENOENT; + } else + res = EINVAL; + break; + case AT_OSRELDATE: + if (buflen == sizeof(int)) { + if (osreldate != 0) { + *(int *)buf = osreldate; + res = 0; + } else + res = ENOENT; + } else + res = EINVAL; + break; + case AT_NCPUS: + if (buflen == sizeof(int)) { + if (ncpus != 0) { + *(int *)buf = ncpus; + res = 0; + } else + res = ENOENT; + } else + res = EINVAL; + break; + case AT_TIMEKEEP: + if (buflen == sizeof(void *)) { + if (timekeep != NULL) { + *(void **)buf = timekeep; + res = 0; + } else + res = ENOENT; + } else + res = EINVAL; + break; + case AT_BSDFLAGS: + if (buflen == sizeof(int)) { + *(int *)buf = bsdflags; + res = 0; + } else + res = EINVAL; + break; + case AT_PS_STRINGS: + if (buflen == sizeof(void *)) { + if (ps_strings != NULL) { + *(void **)buf = ps_strings; + res = 0; + } else + res = ENOENT; + } else + res = EINVAL; + break; + case AT_FXRNG: + if (buflen == sizeof(void *)) { + if (fxrng_seed_version != NULL) { + *(void **)buf = fxrng_seed_version; + res = 0; + } else + res = ENOENT; + } else + res = EINVAL; + break; + case AT_USRSTACKBASE: + if (buflen == sizeof(u_long)) { + if (usrstackbase != 0) { + *(u_long *)buf = usrstackbase; + res = 0; + } else + res = ENOENT; + } else + res = EINVAL; + break; + case AT_USRSTACKLIM: + if (buflen == sizeof(u_long)) { + if (usrstacklim != 0) { + *(u_long *)buf = usrstacklim; + res = 0; + } else + res = ENOENT; + } else + res = EINVAL; + break; + default: + res = ENOENT; + break; + } + return (res); +} diff --git a/lib/libsys/bind.2 b/lib/libsys/bind.2 new file mode 100644 index 000000000000..46325b31bd74 --- /dev/null +++ b/lib/libsys/bind.2 @@ -0,0 +1,138 @@ +.\" Copyright (c) 1983, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd March 30, 2020 +.Dt BIND 2 +.Os +.Sh NAME +.Nm bind +.Nd assign a local protocol address to a socket +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/socket.h +.Ft int +.Fn bind "int s" "const struct sockaddr *addr" "socklen_t addrlen" +.Sh DESCRIPTION +The +.Fn bind +system call +assigns the local protocol address to a socket. +When a socket is created +with +.Xr socket 2 +it exists in an address family space but has no protocol address assigned. +The +.Fn bind +system call requests that +.Fa addr +be assigned to the socket. +.Sh NOTES +Binding an address in the UNIX domain creates a socket in the file +system that must be deleted by the caller when it is no longer +needed (using +.Xr unlink 2 ) . +.Pp +The rules used in address binding vary between communication domains. +Consult the manual entries in section 4 for detailed information. +.Pp +For maximum portability, you should always zero the socket address structure +before populating it and passing it to +.Fn bind . +.Sh RETURN VALUES +.Rv -std bind +.Sh ERRORS +The +.Fn bind +system call will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +Kernel resources to complete the request are +temporarily unavailable. +.It Bq Er EBADF +The +.Fa s +argument +is not a valid descriptor. +.It Bq Er EINVAL +The socket is already bound to an address, and the protocol does not support +binding to a new address; or the socket has been shut down. +.It Bq Er EINVAL +The +.Fa addrlen +argument is not a valid length for the address family. +.It Bq Er ENOTSOCK +The +.Fa s +argument +is not a socket. +.It Bq Er EADDRNOTAVAIL +The specified address is not available from the local machine. +.It Bq Er EADDRINUSE +The specified address is already in use. +.It Bq Er EAFNOSUPPORT +Addresses in the specified address family cannot be used with this socket. +.It Bq Er EACCES +The requested address is protected, and the current user +has inadequate permission to access it. +.It Bq Er EFAULT +The +.Fa addr +argument is not in a valid part of the user +address space. +.El +.Pp +The following errors are specific to binding addresses in the UNIX domain. +.Bl -tag -width EADDRNOTAVA +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +A prefix component of the path name does not exist. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EIO +An I/O error occurred while making the directory entry or allocating the inode. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.It Bq Er EROFS +The name would reside on a read-only file system. +.It Bq Er EISDIR +An empty pathname was specified. +.El +.Sh SEE ALSO +.Xr connect 2 , +.Xr getsockname 2 , +.Xr listen 2 , +.Xr socket 2 +.Sh HISTORY +The +.Fn bind +system call appeared in +.Bx 4.2 . diff --git a/lib/libsys/bindat.2 b/lib/libsys/bindat.2 new file mode 100644 index 000000000000..a31ef2715db9 --- /dev/null +++ b/lib/libsys/bindat.2 @@ -0,0 +1,105 @@ +.\" Copyright (c) 2013 The FreeBSD Foundation +.\" +.\" This documentation was written by Pawel Jakub Dawidek under sponsorship from +.\" the FreeBSD Foundation. +.\" +.\" 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 AUTHORS 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 AUTHORS 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. +.\" +.Dd February 13, 2013 +.Dt BINDAT 2 +.Os +.Sh NAME +.Nm bindat +.Nd assign a local protocol address to a socket +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.Pp +.In fcntl.h +.Ft int +.Fn bindat "int fd" "int s" "const struct sockaddr *addr" "socklen_t addrlen" +.Sh DESCRIPTION +The +.Fn bindat +system call assigns the local protocol address to a socket. +When passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the behavior is identical to a call to +.Xr bind 2 . +Otherwise, +.Fn bindat +works like the +.Xr bind 2 +system call with two exceptions: +.Pp +.Bl -enum -offset indent -compact +.It +It is limited to sockets in the PF_LOCAL domain. +.Pp +.It +If the file path stored in the +.Fa sun_path +field of the sockaddr_un structure is a relative path, it is located relative +to the directory associated with the file descriptor +.Fa fd . +.El +.Sh RETURN VALUES +.Rv -std bindat +.Sh ERRORS +The +.Fn bindat +system call may fail with the same errors as the +.Xr bind 2 +system call or with the following errors: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa sun_path +field does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor. +.It Bq Er ENOTDIR +The +.Fa sun_path +field is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El +.Sh SEE ALSO +.Xr bind 2 , +.Xr connectat 2 , +.Xr socket 2 , +.Xr unix 4 +.Sh AUTHORS +The +.Nm +was developed by +.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net +under sponsorship from the FreeBSD Foundation. diff --git a/lib/libsys/brk.2 b/lib/libsys/brk.2 new file mode 100644 index 000000000000..a90c8bbe9536 --- /dev/null +++ b/lib/libsys/brk.2 @@ -0,0 +1,187 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd June 2, 2018 +.Dt BRK 2 +.Os +.Sh NAME +.Nm brk , +.Nm sbrk +.Nd change data segment size +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn brk "const void *addr" +.Ft void * +.Fn sbrk "intptr_t incr" +.Sh DESCRIPTION +.Bf -symbolic +The +.Fn brk +and +.Fn sbrk +functions are legacy interfaces from before the +advent of modern virtual memory management. +They are deprecated and not present on the arm64 or riscv architectures. +The +.Xr mmap 2 +interface should be used to allocate pages instead. +.Ef +.Pp +The +.Fn brk +and +.Fn sbrk +functions are used to change the amount of memory allocated in a +process's data segment. +They do this by moving the location of the +.Dq break . +The break is the first address after the end of the process's +uninitialized data segment (also known as the +.Dq BSS ) . +.Pp +The +.Fn brk +function +sets the break to +.Fa addr . +.Pp +The +.Fn sbrk +function raises the break by +.Fa incr +bytes, thus allocating at least +.Fa incr +bytes of new memory in the data segment. +If +.Fa incr +is negative, +the break is lowered by +.Fa incr +bytes. +.Sh NOTES +While the actual process data segment size maintained by the kernel will only +grow or shrink in page sizes, these functions allow setting the break +to unaligned values (i.e., it may point to any address inside the last +page of the data segment). +.Pp +The current value of the program break may be determined by calling +.Fn sbrk 0 . +See also +.Xr end 3 . +.Pp +The +.Xr getrlimit 2 +system call may be used to determine +the maximum permissible size of the +data segment. +It will not be possible to set the break +beyond +.Dq Va etext No + Va rlim.rlim_max +where the +.Va rlim.rlim_max +value is returned from a call to +.Fn getrlimit RLIMIT_DATA &rlim . +(See +.Xr end 3 +for the definition of +.Va etext ) . +.Sh RETURN VALUES +.Rv -std brk +.Pp +The +.Fn sbrk +function returns the prior break value if successful; +otherwise the value +.Po Vt "void *" Pc Ns \-1 +is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn brk +and +.Fn sbrk +functions +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The requested break value was beyond the beginning of the data segment. +.It Bq Er ENOMEM +The data segment size limit, as set by +.Xr setrlimit 2 , +was exceeded. +.It Bq Er ENOMEM +Insufficient space existed in the swap area +to support the expansion of the data segment. +.El +.Sh SEE ALSO +.Xr execve 2 , +.Xr getrlimit 2 , +.Xr mmap 2 , +.Xr end 3 , +.Xr free 3 , +.Xr malloc 3 +.Sh HISTORY +The +.Fn brk +function appeared in +.At v7 . +.Fx 11.0 +introduced the arm64 and riscv architectures which do not support +.Fn brk +or +.Fn sbrk . +.Sh BUGS +Mixing +.Fn brk +or +.Fn sbrk +with +.Xr malloc 3 , +.Xr free 3 , +or similar functions will result in non-portable program behavior. +.Pp +Setting the break may fail due to a temporary lack of +swap space. +It is not possible to distinguish this +from a failure caused by exceeding the maximum size of +the data segment without consulting +.Xr getrlimit 2 . +.Pp +.Fn sbrk +is sometimes used to monitor heap use by calling with an argument of 0. +The result is unlikely to reflect actual utilization in combination with an +.Xr mmap 2 +based malloc. +.Pp +.Fn brk +and +.Fn sbrk +are not thread-safe. diff --git a/lib/libsys/cap_enter.2 b/lib/libsys/cap_enter.2 new file mode 100644 index 000000000000..90c089ae9b07 --- /dev/null +++ b/lib/libsys/cap_enter.2 @@ -0,0 +1,161 @@ +.\" +.\" Copyright (c) 2008-2009 Robert N. M. Watson +.\" All rights reserved. +.\" +.\" This software was developed at the University of Cambridge Computer +.\" Laboratory with support from a grant from Google, Inc. +.\" +.\" 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. +.\" +.Dd March 9, 2023 +.Dt CAP_ENTER 2 +.Os +.Sh NAME +.Nm cap_enter , +.Nm cap_getmode +.Nd Capability mode system calls +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/capsicum.h +.Ft int +.Fn cap_enter "void" +.Ft int +.Fn cap_getmode "u_int *modep" +.Sh DESCRIPTION +.Fn cap_enter +places the current process into capability mode, a mode of execution in which +processes may only issue system calls operating on file descriptors or +reading limited global system state. +Access to global name spaces, such as file system or IPC name spaces, is +prevented. +If the process is already in a capability mode sandbox, the system call is a +no-op. +Future process descendants created with +.Xr fork 2 +or +.Xr pdfork 2 +will be placed in capability mode from inception. +.Pp +When combined with +.Xr cap_rights_limit 2 , +.Xr cap_ioctls_limit 2 , +.Xr cap_fcntls_limit 2 , +.Fn cap_enter +may be used to create kernel-enforced sandboxes in which +appropriately-crafted applications or application components may be run. +.Pp +.Fn cap_getmode +returns a flag indicating whether or not the process is in a capability mode +sandbox. +.Sh RUN-TIME SETTINGS +If the +.Dv kern.trap_enotcap +sysctl MIB is set to a non-zero value, then for any process executing in a +capability mode sandbox, any syscall which results in either an +.Er ENOTCAPABLE +or +.Er ECAPMODE +error also generates the synchronous +.Dv SIGTRAP +signal to the thread on the syscall return. +On signal delivery, the +.Va si_errno +member of the +.Fa siginfo +signal handler parameter is set to the syscall error value, +and the +.Va si_code +member is set to +.Dv TRAP_CAP . +.Pp +See also the +.Dv PROC_TRAPCAP_CTL +and +.Dv PROC_TRAPCAP_STATUS +operations of the +.Xr procctl 2 +function for similar per-process functionality. +.Sh RETURN VALUES +.Rv -std cap_enter cap_getmode +.Pp +When the process is in capability mode, +.Fn cap_getmode +sets the flag to a non-zero value. +A zero value means the process is not in capability mode. +.Sh ERRORS +The +.Fn cap_enter +and +.Fn cap_getmode +system calls +will fail if: +.Bl -tag -width Er +.It Bq Er ENOSYS +The running kernel was compiled without +.Cd "options CAPABILITY_MODE" . +.El +.Pp +The +.Fn cap_getmode +system call may also return the following error: +.Bl -tag -width Er +.It Bq Er EFAULT +Pointer +.Fa modep +points outside the process's allocated address space. +.El +.Sh SEE ALSO +.Xr cap_fcntls_limit 2 , +.Xr cap_ioctls_limit 2 , +.Xr cap_rights_limit 2 , +.Xr fexecve 2 , +.Xr procctl 2 , +.Xr cap_sandboxed 3 , +.Xr capsicum 4 , +.Xr sysctl 9 +.Sh HISTORY +The +.Fn cap_getmode +system call first appeared in +.Fx 8.3 . +Support for capabilities and capabilities mode was developed as part of the +.Tn TrustedBSD +Project. +.Sh AUTHORS +These functions and the capability facility were created by +.An "Robert N. M. Watson" +at the University of Cambridge Computer Laboratory with support from a grant +from Google, Inc. +.Sh CAVEATS +Creating effective process sandboxes is a tricky process that involves +identifying the least possible rights required by the process and then +passing those rights into the process in a safe manner. +Consumers of +.Fn cap_enter +should also be aware of other inherited rights, such as access to VM +resources, memory contents, and other process properties that should be +considered. +It is advisable to use +.Xr fexecve 2 +to create a runtime environment inside the sandbox that has as few implicitly +acquired rights as possible. diff --git a/lib/libsys/cap_fcntls_limit.2 b/lib/libsys/cap_fcntls_limit.2 new file mode 100644 index 000000000000..299594e9be66 --- /dev/null +++ b/lib/libsys/cap_fcntls_limit.2 @@ -0,0 +1,132 @@ +.\" +.\" Copyright (c) 2012 The FreeBSD Foundation +.\" +.\" This documentation was written by Pawel Jakub Dawidek under sponsorship +.\" the FreeBSD Foundation. +.\" +.\" 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. +.\" +.Dd March 9, 2023 +.Dt CAP_FCNTLS_LIMIT 2 +.Os +.Sh NAME +.Nm cap_fcntls_limit , +.Nm cap_fcntls_get +.Nd manage allowed fcntl commands +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/capsicum.h +.Ft int +.Fn cap_fcntls_limit "int fd" "uint32_t fcntlrights" +.Ft int +.Fn cap_fcntls_get "int fd" "uint32_t *fcntlrightsp" +.Sh DESCRIPTION +If a file descriptor is granted the +.Dv CAP_FCNTL +capability right, the list of allowed +.Xr fcntl 2 +commands can be selectively reduced (but never expanded) with the +.Fn cap_fcntls_limit +system call. +.Pp +A bitmask of allowed fcntls commands for a given file descriptor can be obtained +with the +.Fn cap_fcntls_get +system call. +.Sh FLAGS +The following flags may be specified in the +.Fa fcntlrights +argument or returned in the +.Fa fcntlrightsp +argument: +.Bl -tag -width CAP_FCNTL_GETOWN +.It Dv CAP_FCNTL_GETFL +Permit +.Dv F_GETFL +command. +.It Dv CAP_FCNTL_SETFL +Permit +.Dv F_SETFL +command. +.It Dv CAP_FCNTL_GETOWN +Permit +.Dv F_GETOWN +command. +.It Dv CAP_FCNTL_SETOWN +Permit +.Dv F_SETOWN +command. +.El +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +.Fn cap_fcntls_limit +succeeds unless: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid descriptor. +.It Bq Er EINVAL +An invalid flag has been passed in +.Fa fcntlrights . +.It Bq Er ENOTCAPABLE +.Fa fcntlrights +would expand the list of allowed +.Xr fcntl 2 +commands. +.El +.Pp +.Fn cap_fcntls_get +succeeds unless: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid descriptor. +.It Bq Er EFAULT +The +.Fa fcntlrightsp +argument points at an invalid address. +.It Bq Er ENOSYS +The running kernel was compiled without +.Cd "options CAPABILITY_MODE" . +.El +.Sh SEE ALSO +.Xr cap_ioctls_limit 2 , +.Xr cap_rights_limit 2 , +.Xr fcntl 2 +.Sh HISTORY +The +.Fn cap_fcntls_get +and +.Fn cap_fcntls_limit +system calls first appeared in +.Fx 8.3 . +Support for capabilities and capabilities mode was developed as part of the +.Tn TrustedBSD +Project. +.Sh AUTHORS +This function was created by +.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net +under sponsorship of the FreeBSD Foundation. diff --git a/lib/libsys/cap_ioctls_limit.2 b/lib/libsys/cap_ioctls_limit.2 new file mode 100644 index 000000000000..c9d468ba8fac --- /dev/null +++ b/lib/libsys/cap_ioctls_limit.2 @@ -0,0 +1,161 @@ +.\" +.\" Copyright (c) 2012 The FreeBSD Foundation +.\" +.\" This documentation was written by Pawel Jakub Dawidek under sponsorship +.\" the FreeBSD Foundation. +.\" +.\" 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. +.\" +.Dd March 9, 2023 +.Dt CAP_IOCTLS_LIMIT 2 +.Os +.Sh NAME +.Nm cap_ioctls_limit , +.Nm cap_ioctls_get +.Nd manage allowed ioctl commands +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/capsicum.h +.Ft int +.Fn cap_ioctls_limit "int fd" "const unsigned long *cmds" "size_t ncmds" +.Ft ssize_t +.Fn cap_ioctls_get "int fd" "unsigned long *cmds" "size_t maxcmds" +.Sh DESCRIPTION +If a file descriptor is granted the +.Dv CAP_IOCTL +capability right, the list of allowed +.Xr ioctl 2 +commands can be selectively reduced (but never expanded) with the +.Fn cap_ioctls_limit +system call. +The +.Fa cmds +argument is an array of +.Xr ioctl 2 +commands and the +.Fa ncmds +argument specifies the number of elements in the array. +There can be up to +.Va 256 +elements in the array. +Including an element that has been previously revoked will generate an error. +After a successful call only those listed in the array may be used. +.Pp +The list of allowed ioctl commands for a given file descriptor can be obtained +with the +.Fn cap_ioctls_get +system call. +The +.Fa cmds +argument points at memory that can hold up to +.Fa maxcmds +values. +The function populates the provided buffer with up to +.Fa maxcmds +elements, but always returns the total number of ioctl commands allowed for the +given file descriptor. +The total number of ioctls commands for the given file descriptor can be +obtained by passing +.Dv NULL as the +.Fa cmds +argument and +.Va 0 +as the +.Fa maxcmds +argument. +If all ioctl commands are allowed +.Dv ( CAP_IOCTL +capability right is assigned to the file descriptor and the +.Fn cap_ioctls_limit +system call was never called for this file descriptor), the +.Fn cap_ioctls_get +system call will return +.Dv CAP_IOCTLS_ALL +and will not modify the buffer pointed to by the +.Fa cmds +argument. +.Sh RETURN VALUES +.Rv -std cap_ioctls_limit +.Pp +The +.Fn cap_ioctls_get +function, if successful, returns the total number of allowed ioctl commands or +the value +.Dv CAP_IOCTLS_ALL +if all ioctls commands are allowed. +On failure the value +.Va -1 +is returned and the global variable errno is set to indicate the error. +.Sh ERRORS +The +.Fn cap_ioctls_limit +and +.Fn cap_ioctls_get +system calls will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid descriptor. +.It Bq Er EFAULT +The +.Fa cmds +argument points at an invalid address. +.It Bq Er ENOSYS +The running kernel was compiled without +.Cd "options CAPABILITY_MODE" . +.El +.Pp +The +.Fn cap_ioctls_limit +system call may also return the following errors: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa ncmds +argument is greater than +.Va 256 . +.It Bq Er ENOTCAPABLE +.Fa cmds +would expand the list of allowed +.Xr ioctl 2 +commands. +.El +.Sh SEE ALSO +.Xr cap_fcntls_limit 2 , +.Xr cap_rights_limit 2 , +.Xr ioctl 2 +.Sh HISTORY +The +.Fn cap_ioctls_get +and +.Fn cap_ioctls_limit +system calls first appeared in +.Fx 8.3 . +Support for capabilities and capabilities mode was developed as part of the +.Tn TrustedBSD +Project. +.Sh AUTHORS +This function was created by +.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net +under sponsorship of the FreeBSD Foundation. diff --git a/lib/libsys/cap_rights_limit.2 b/lib/libsys/cap_rights_limit.2 new file mode 100644 index 000000000000..8372d07f6a5c --- /dev/null +++ b/lib/libsys/cap_rights_limit.2 @@ -0,0 +1,164 @@ +.\" +.\" Copyright (c) 2008-2010 Robert N. M. Watson +.\" Copyright (c) 2012-2013 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" This software was developed at the University of Cambridge Computer +.\" Laboratory with support from a grant from Google, Inc. +.\" +.\" Portions of this documentation were written by Pawel Jakub Dawidek +.\" under sponsorship from the FreeBSD Foundation. +.\" +.\" 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. +.\" +.Dd April 27, 2024 +.Dt CAP_RIGHTS_LIMIT 2 +.Os +.Sh NAME +.Nm cap_rights_limit +.Nd limit capability rights +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/capsicum.h +.Ft int +.Fn cap_rights_limit "int fd" "const cap_rights_t *rights" +.Sh DESCRIPTION +When a file descriptor is created by a function such as +.Xr fhopen 2 , +.Xr kqueue 2 , +.Xr mq_open 2 , +.Xr open 2 , +.Xr pdfork 2 , +.Xr pipe 2 , +.Xr shm_open 2 , +.Xr socket 2 +or +.Xr socketpair 2 , +it is assigned all capability rights; for +.Xr accept 2 , +.Xr accept4 2 +or +.Xr openat 2 , +it inherits capability rights from the "parent" file descriptor. +Those rights can be reduced (but never expanded) by using the +.Fn cap_rights_limit +system call. +Once capability rights are reduced, operations on the file descriptor will be +limited to those permitted by +.Fa rights . +.Pp +The +.Fa rights +argument should be prepared using +.Xr cap_rights_init 3 +family of functions. +.Pp +Capability rights assigned to a file descriptor can be obtained with the +.Xr cap_rights_get 3 +function. +.Pp +The complete list of the capability rights can be found in the +.Xr rights 4 +manual page. +.Sh RETURN VALUES +.Rv -std +.Sh EXAMPLES +The following example demonstrates how to limit file descriptor capability +rights to allow reading only. +.Bd -literal +cap_rights_t setrights; +char buf[1]; +int fd; + +fd = open("/tmp/foo", O_RDWR); +if (fd < 0) + err(1, "open() failed"); + +if (cap_enter() < 0) + err(1, "cap_enter() failed"); + +cap_rights_init(&setrights, CAP_READ); +if (cap_rights_limit(fd, &setrights) < 0) + err(1, "cap_rights_limit() failed"); + +buf[0] = 'X'; + +if (write(fd, buf, sizeof(buf)) > 0) + errx(1, "write() succeeded!"); + +if (read(fd, buf, sizeof(buf)) < 0) + err(1, "read() failed"); +.Ed +.Sh ERRORS +.Fn cap_rights_limit +succeeds unless: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid active descriptor. +.It Bq Er EINVAL +An invalid right has been requested in +.Fa rights . +.It Bq Er ENOSYS +The running kernel was compiled without +.Cd "options CAPABILITY_MODE" . +.It Bq Er ENOTCAPABLE +The +.Fa rights +argument contains capability rights not present for the given file descriptor. +Capability rights list can only be reduced, never expanded. +.El +.Sh SEE ALSO +.Xr accept 2 , +.Xr accept4 2 , +.Xr cap_enter 2 , +.Xr fhopen 2 , +.Xr kqueue 2 , +.Xr mq_open 2 , +.Xr open 2 , +.Xr openat 2 , +.Xr pdfork 2 , +.Xr pipe 2 , +.Xr read 2 , +.Xr shm_open 2 , +.Xr socket 2 , +.Xr socketpair 2 , +.Xr write 2 , +.Xr cap_rights_get 3 , +.Xr cap_rights_init 3 , +.Xr err 3 , +.Xr capsicum 4 , +.Xr rights 4 +.Sh HISTORY +The +.Fn cap_rights_limit +function first appeared in +.Fx 8.3 . +Support for capabilities and capabilities mode was developed as part of the +.Tn TrustedBSD +Project. +.Sh AUTHORS +This function was created by +.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net +under sponsorship of the FreeBSD Foundation. diff --git a/lib/libsys/chdir.2 b/lib/libsys/chdir.2 new file mode 100644 index 000000000000..991529f11f3d --- /dev/null +++ b/lib/libsys/chdir.2 @@ -0,0 +1,131 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd March 30, 2020 +.Dt CHDIR 2 +.Os +.Sh NAME +.Nm chdir , +.Nm fchdir +.Nd change current working directory +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn chdir "const char *path" +.Ft int +.Fn fchdir "int fd" +.Sh DESCRIPTION +The +.Fa path +argument points to the pathname of a directory. +The +.Fn chdir +system call +causes the named directory +to become the current working directory, that is, +the starting point for path searches of pathnames not beginning with +a slash, +.Ql / . +.Pp +The +.Fn fchdir +system call +causes the directory referenced by +.Fa fd +to become the current working directory, +the starting point for path searches of pathnames not beginning with +a slash, +.Ql / . +.Pp +In order for a directory to become the current directory, +a process must have execute (search) access to the directory. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn chdir +system call +will fail and the current working directory will be unchanged if +one or more of the following are true: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named directory does not exist. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EACCES +Search permission is denied for any component of +the path name. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.El +.Pp +The +.Fn fchdir +system call +will fail and the current working directory will be unchanged if +one or more of the following are true: +.Bl -tag -width Er +.It Bq Er EACCES +Search permission is denied for the directory referenced by the +file descriptor. +.It Bq Er ENOTDIR +The file descriptor does not reference a directory. +.It Bq Er EBADF +The argument +.Fa fd +is not a valid file descriptor. +.El +.Sh SEE ALSO +.Xr chroot 2 +.Sh STANDARDS +The +.Fn chdir +system call is expected to conform to +.St -p1003.1-90 . +.Sh HISTORY +The +.Fn chdir +system call appeared in +.At v1 . +The +.Fn fchdir +system call appeared in +.Bx 4.2 . diff --git a/lib/libsys/chflags.2 b/lib/libsys/chflags.2 new file mode 100644 index 000000000000..ec190df7fb19 --- /dev/null +++ b/lib/libsys/chflags.2 @@ -0,0 +1,356 @@ +.\" Copyright (c) 1989, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd March 30, 2021 +.Dt CHFLAGS 2 +.Os +.Sh NAME +.Nm chflags , +.Nm lchflags , +.Nm fchflags , +.Nm chflagsat +.Nd set file flags +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/stat.h +.In unistd.h +.Ft int +.Fn chflags "const char *path" "unsigned long flags" +.Ft int +.Fn lchflags "const char *path" "unsigned long flags" +.Ft int +.Fn fchflags "int fd" "unsigned long flags" +.Ft int +.Fn chflagsat "int fd" "const char *path" "unsigned long flags" "int atflag" +.Sh DESCRIPTION +The file whose name +is given by +.Fa path +or referenced by the descriptor +.Fa fd +has its flags changed to +.Fa flags . +.Pp +The +.Fn lchflags +system call is like +.Fn chflags +except in the case where the named file is a symbolic link, +in which case +.Fn lchflags +will change the flags of the link itself, +rather than the file it points to. +.Pp +The +.Fn chflagsat +is equivalent to either +.Fn chflags +or +.Fn lchflags +depending on the +.Fa atflag +except in the case where +.Fa path +specifies a relative path. +In this case the file to be changed is determined relative to the directory +associated with the file descriptor +.Fa fd +instead of the current working directory. +The values for the +.Fa atflag +are constructed by a bitwise-inclusive OR of flags from the following list, +defined in +.In fcntl.h : +.Bl -tag -width indent +.It Dv AT_SYMLINK_NOFOLLOW +If +.Fa path +names a symbolic link, then the flags of the symbolic link are changed. +.It Dv AT_RESOLVE_BENEATH +Only walk paths below the directory specified by the +.Ar fd +descriptor. +See the description of the +.Dv O_RESOLVE_BENEATH +flag in the +.Xr open 2 +manual page. +.It Dv AT_EMPTY_PATH +If the +.Fa path +argument is an empty string, operate on the file or directory +referenced by the descriptor +.Fa fd . +If +.Fa fd +is equal to +.Dv AT_FDCWD , +operate on the current working directory. +.El +.Pp +If +.Fn chflagsat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used. +If also +.Fa atflag +is zero, the behavior is identical to a call to +.Fn chflags . +.Pp +The flags specified are formed by +.Em or Ns 'ing +the following values +.Pp +.Bl -tag -width ".Dv SF_IMMUTABLE" -compact -offset indent +.It Dv SF_APPEND +The file may only be appended to. +.It Dv SF_ARCHIVED +The file has been archived. +This flag means the opposite of the DOS, Windows and CIFS +FILE_ATTRIBUTE_ARCHIVE attribute. +This flag has been deprecated, and may be removed in a future release. +.It Dv SF_IMMUTABLE +The file may not be changed. +.It Dv SF_NOUNLINK +The file may not be renamed or deleted. +.It Dv SF_SNAPSHOT +The file is a snapshot file. +.It Dv UF_APPEND +The file may only be appended to. +.It Dv UF_ARCHIVE +The file needs to be archived. +This flag has the same meaning as the DOS, Windows and CIFS +FILE_ATTRIBUTE_ARCHIVE attribute. +Filesystems in FreeBSD may or may not have special handling for this flag. +For instance, ZFS tracks changes to files and will set this bit when a +file is updated. +UFS only stores the flag, and relies on the application to change it when +needed. +.It Dv UF_HIDDEN +The file may be hidden from directory listings at the application's +discretion. +The file has the DOS, Windows and CIFS FILE_ATTRIBUTE_HIDDEN attribute. +.It Dv UF_IMMUTABLE +The file may not be changed. +.It Dv UF_NODUMP +Do not dump the file. +.It Dv UF_NOUNLINK +The file may not be renamed or deleted. +.It Dv UF_OFFLINE +The file is offline, or has the Windows and CIFS FILE_ATTRIBUTE_OFFLINE +attribute. +Filesystems in FreeBSD store and display this flag, but do not provide any +special handling when it is set. +.It Dv UF_OPAQUE +The directory is opaque when viewed through a union stack. +.It Dv UF_READONLY +The file is read only, and may not be written or appended. +Filesystems may use this flag to maintain compatibility with the DOS, Windows +and CIFS FILE_ATTRIBUTE_READONLY attribute. +.It Dv UF_REPARSE +The file contains a Windows reparse point and has the Windows and CIFS +FILE_ATTRIBUTE_REPARSE_POINT attribute. +.It Dv UF_SPARSE +The file has the Windows FILE_ATTRIBUTE_SPARSE_FILE attribute. +This may also be used by a filesystem to indicate a sparse file. +.It Dv UF_SYSTEM +The file has the DOS, Windows and CIFS FILE_ATTRIBUTE_SYSTEM attribute. +Filesystems in FreeBSD may store and display this flag, but do not provide +any special handling when it is set. +.El +.Pp +If one of +.Dv SF_IMMUTABLE , SF_APPEND , +or +.Dv SF_NOUNLINK +is set a non-super-user cannot change any flags and even the super-user +can change flags only if securelevel is 0. +(See +.Xr init 8 +for details.) +.Pp +The +.Dv UF_IMMUTABLE , UF_APPEND , UF_NOUNLINK , UF_NODUMP , +and +.Dv UF_OPAQUE +flags may be set or unset by either the owner of a file or the super-user. +.Pp +The +.Dv SF_IMMUTABLE , SF_APPEND , SF_NOUNLINK , +and +.Dv SF_ARCHIVED +flags may only be set or unset by the super-user. +Attempts to toggle these flags by non-super-users are rejected. +These flags may be set at any time, but normally may only be unset when +the system is in single-user mode. +(See +.Xr init 8 +for details.) +.Pp +The implementation of all flags is filesystem-dependent. +See the description of the +.Dv UF_ARCHIVE +flag above for one example of the differences in behavior. +Care should be exercised when writing applications to account for +support or lack of support of these flags in various filesystems. +.Pp +The +.Dv SF_SNAPSHOT +flag is maintained by the system and cannot be toggled. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn chflags +system call will fail if: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named file does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EPERM +The effective user ID does not match the owner of the file and +the effective user ID is not the super-user. +.It Bq Er EPERM +One of +.Dv SF_IMMUTABLE , SF_APPEND , +or +.Dv SF_NOUNLINK +is set and the user is either not the super-user or +securelevel is greater than 0. +.It Bq Er EPERM +A non-super-user attempted to toggle one of +.Dv SF_ARCHIVED , SF_IMMUTABLE , SF_APPEND , +or +.Dv SF_NOUNLINK . +.It Bq Er EPERM +An attempt was made to toggle the +.Dv SF_SNAPSHOT +flag. +.It Bq Er EROFS +The named file resides on a read-only file system. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.It Bq Er EIO +An +.Tn I/O +error occurred while reading from or writing to the file system. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.It Bq Er EOPNOTSUPP +The underlying file system does not support file flags, or +does not support all of the flags set in +.Fa flags . +.El +.Pp +The +.Fn fchflags +system call will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The descriptor is not valid. +.It Bq Er EINVAL +The +.Fa fd +argument +refers to a socket, not to a file. +.It Bq Er EPERM +The effective user ID does not match the owner of the file and +the effective user ID is not the super-user. +.It Bq Er EPERM +One of +.Dv SF_IMMUTABLE , SF_APPEND , +or +.Dv SF_NOUNLINK +is set and the user is either not the super-user or +securelevel is greater than 0. +.It Bq Er EPERM +A non-super-user attempted to toggle one of +.Dv SF_ARCHIVED , SF_IMMUTABLE , SF_APPEND , +or +.Dv SF_NOUNLINK . +.It Bq Er EPERM +An attempt was made to toggle the +.Dv SF_SNAPSHOT +flag. +.It Bq Er EROFS +The file resides on a read-only file system. +.It Bq Er EIO +An +.Tn I/O +error occurred while reading from or writing to the file system. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.It Bq Er EOPNOTSUPP +The underlying file system does not support file flags, or +does not support all of the flags set in +.Fa flags . +.It Bq Er ENOTCAPABLE +.Fa path +is an absolute path, +or contained a ".." component leading to a +directory outside of the directory hierarchy specified by +.Fa fd , +and the process is in capability mode or the +.Dv AT_RESOLVE_BENEATH +flag was specified. +.El +.Sh SEE ALSO +.Xr chflags 1 , +.Xr fflagstostr 3 , +.Xr strtofflags 3 , +.Xr init 8 , +.Xr mount_unionfs 8 +.Sh HISTORY +The +.Fn chflags +and +.Fn fchflags +system calls first appeared in +.Bx 4.4 . +The +.Fn lchflags +system call first appeared in +.Fx 5.0 . +The +.Fn chflagsat +system call first appeared in +.Fx 10.0 . diff --git a/lib/libsys/chmod.2 b/lib/libsys/chmod.2 new file mode 100644 index 000000000000..2db182a95fcc --- /dev/null +++ b/lib/libsys/chmod.2 @@ -0,0 +1,364 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd October 31, 2024 +.Dt CHMOD 2 +.Os +.Sh NAME +.Nm chmod , +.Nm fchmod , +.Nm lchmod , +.Nm fchmodat +.Nd change mode of file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/stat.h +.Ft int +.Fn chmod "const char *path" "mode_t mode" +.Ft int +.Fn fchmod "int fd" "mode_t mode" +.Ft int +.Fn lchmod "const char *path" "mode_t mode" +.Ft int +.Fn fchmodat "int fd" "const char *path" "mode_t mode" "int flag" +.Sh DESCRIPTION +The file permission bits of the file named specified by +.Fa path +or referenced by the file descriptor +.Fa fd +are changed to +.Fa mode . +The +.Fn chmod +system call verifies that the process owner (user) either owns +the file specified by +.Fa path +(or +.Fa fd ) , +or +is the super-user. +The +.Fn chmod +system call follows symbolic links to operate on the target of the link +rather than the link itself. +.Pp +The +.Fn lchmod +system call is similar to +.Fn chmod +but does not follow symbolic links. +.Pp +The +.Fn fchmodat +is equivalent to either +.Fn chmod +or +.Fn lchmod +depending on the +.Fa flag +except in the case where +.Fa path +specifies a relative path. +In this case the file to be changed is determined relative to the directory +associated with the file descriptor +.Fa fd +instead of the current working directory. +The values for the +.Fa flag +are constructed by a bitwise-inclusive OR of flags from the following list, defined +in +.In fcntl.h : +.Bl -tag -width indent +.It Dv AT_SYMLINK_NOFOLLOW +If +.Fa path +names a symbolic link, then the mode of the symbolic link is changed. +.It Dv AT_RESOLVE_BENEATH +Only walk paths below the directory specified by the +.Ar fd +descriptor. +See the description of the +.Dv O_RESOLVE_BENEATH +flag in the +.Xr open 2 +manual page. +.It Dv AT_EMPTY_PATH +If the +.Fa path +argument is an empty string, operate on the file or directory +referenced by the descriptor +.Fa fd . +If +.Fa fd +is equal to +.Dv AT_FDCWD , +operate on the current working directory. +.El +.Pp +If +.Fn fchmodat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used. +If also +.Fa flag +is zero, the behavior is identical to a call to +.Fn chmod . +.Pp +A mode is created from +.Em or'd +permission bit masks +defined in +.In sys/stat.h : +.Pp +.Bd -literal -offset indent -compact +#define S_IRWXU 0000700 /* RWX mask for owner */ +#define S_IRUSR 0000400 /* R for owner */ +#define S_IWUSR 0000200 /* W for owner */ +#define S_IXUSR 0000100 /* X for owner */ + +#define S_IRWXG 0000070 /* RWX mask for group */ +#define S_IRGRP 0000040 /* R for group */ +#define S_IWGRP 0000020 /* W for group */ +#define S_IXGRP 0000010 /* X for group */ + +#define S_IRWXO 0000007 /* RWX mask for other */ +#define S_IROTH 0000004 /* R for other */ +#define S_IWOTH 0000002 /* W for other */ +#define S_IXOTH 0000001 /* X for other */ + +#define S_ISUID 0004000 /* set user id on execution */ +#define S_ISGID 0002000 /* set group id on execution */ +#define S_ISVTX 0001000 /* sticky bit */ +.Ed +.Pp +The non-standard +.Dv S_ISTXT +is a synonym for +.Dv S_ISVTX . +.Pp +The +.Fx +VM system totally ignores the sticky bit +.Pq Dv S_ISVTX +for executables. +On UFS-based file systems (FFS, LFS) the sticky +bit may only be set upon directories. +.Pp +If mode +.Dv S_ISVTX +(the `sticky bit') is set on a directory, +an unprivileged user may not delete or rename +files of other users in that directory. +The sticky bit may be +set by any user on a directory which the user owns or has appropriate +permissions. +For more details of the properties of the sticky bit, see +.Xr sticky 7 . +.Pp +If mode ISUID (set UID) is set on a directory, +and the MNT_SUIDDIR option was used in the mount of the file system, +then the owner of any new files and sub-directories +created within this directory are set +to be the same as the owner of that directory. +If this function is enabled, new directories will inherit +the bit from their parents. +Execute bits are removed from +the file, and it will not be given to root. +This behavior does not change the +requirements for the user to be allowed to write the file, but only the eventual +owner after it has been created. +Group inheritance is not affected. +.Pp +This feature is designed for use on fileservers serving PC users via +ftp, SAMBA, or netatalk. +It provides security holes for shell users and as +such should not be used on shell machines, especially on home directories. +This option requires the SUIDDIR +option in the kernel to work. +Only UFS file systems support this option. +For more details of the suiddir mount option, see +.Xr mount 8 . +.Pp +Writing or changing the owner of a file +turns off the set-user-id and set-group-id bits +unless the user is the super-user. +This makes the system somewhat more secure +by protecting set-user-id (set-group-id) files +from remaining set-user-id (set-group-id) if they are modified, +at the expense of a degree of compatibility. +.Pp +While it is normally an error to invoke +.Fn fchmod +on a socket, it is possible to do so on +.Dv AF_LOCAL +sockets before they are bound to a file name; see +.Xr unix 4 . +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn chmod +system call +will fail and the file mode will be unchanged if: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named file does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EPERM +The effective user ID does not match the owner of the file and +the effective user ID is not the super-user. +.It Bq Er EPERM +The effective user ID is not the super-user, the effective user ID do match the +owner of the file, but the group ID of the file does not match the effective +group ID nor one of the supplementary group IDs. +.It Bq Er EPERM +The named file has its immutable or append-only flag set, see the +.Xr chflags 2 +manual page for more information. +.It Bq Er EROFS +The named file resides on a read-only file system. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.It Bq Er EFTYPE +The effective user ID is not the super-user, the mode includes the sticky bit +.Dv ( S_ISVTX ) , +and path does not refer to a directory. +.El +.Pp +The +.Fn fchmod +system call will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The descriptor is not valid. +.It Bq Er EINVAL +The +.Fa fd +argument +refers to a socket, not to a file. +.It Bq Er EROFS +The file resides on a read-only file system. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.El +.Pp +In addition to the +.Fn chmod +errors, +.Fn fchmodat +fails if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Fa AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er EINVAL +The value of the +.Fa flag +argument is not valid. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.It Bq Er ENOTCAPABLE +.Fa path +is an absolute path, +or contained a ".." component leading to a +directory outside of the directory hierarchy specified by +.Fa fd , +and the process is in capability mode or the +.Dv AT_RESOLVE_BENEATH +flag was specified. +.El +.Sh SEE ALSO +.Xr chmod 1 , +.Xr chflags 2 , +.Xr chown 2 , +.Xr open 2 , +.Xr stat 2 , +.Xr sticky 7 +.Sh STANDARDS +The +.Fn chmod +system call is expected to conform to +.St -p1003.1-90 , +except for the return of +.Er EFTYPE . +The +.Dv S_ISVTX +bit on directories is expected to conform to +.St -susv3 . +The +.Fn fchmodat +system call is expected to conform to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn chmod +function appeared in +.At v1 . +The +.Fn fchmod +system call appeared in +.Bx 4.2 . +The +.Fn lchmod +system call appeared in +.Fx 3.0 . +The +.Fn fchmodat +system call appeared in +.Fx 8.0 . diff --git a/lib/libsys/chown.2 b/lib/libsys/chown.2 new file mode 100644 index 000000000000..2e5ab7750d72 --- /dev/null +++ b/lib/libsys/chown.2 @@ -0,0 +1,298 @@ +.\" Copyright (c) 1980, 1991, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd March 30, 2021 +.Dt CHOWN 2 +.Os +.Sh NAME +.Nm chown , +.Nm fchown , +.Nm lchown , +.Nm fchownat +.Nd change owner and group of a file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn chown "const char *path" "uid_t owner" "gid_t group" +.Ft int +.Fn fchown "int fd" "uid_t owner" "gid_t group" +.Ft int +.Fn lchown "const char *path" "uid_t owner" "gid_t group" +.Ft int +.Fn fchownat "int fd" "const char *path" "uid_t owner" "gid_t group" "int flag" +.Sh DESCRIPTION +The owner ID and group ID of the file +named by +.Fa path +or referenced by +.Fa fd +is changed as specified by the arguments +.Fa owner +and +.Fa group . +The owner of a file may change the +.Fa group +to a group of which +he or she is a member, +but the change +.Fa owner +capability is restricted to the super-user. +.Pp +The +.Fn chown +system call +clears the set-user-id and set-group-id bits +on the file +to prevent accidental or mischievous creation of +set-user-id and set-group-id programs if not executed +by the super-user. +The +.Fn chown +system call +follows symbolic links to operate on the target of the link +rather than the link itself. +.Pp +The +.Fn fchown +system call +is particularly useful when used in conjunction +with the file locking primitives (see +.Xr flock 2 ) . +.Pp +The +.Fn lchown +system call is similar to +.Fn chown +but does not follow symbolic links. +.Pp +The +.Fn fchownat +system call is equivalent to the +.Fn chown +and +.Fn lchown +except in the case where +.Fa path +specifies a relative path. +In this case the file to be changed is determined relative to the directory +associated with the file descriptor +.Fa fd +instead of the current working directory. +.Pp +Values for +.Fa flag +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.In fcntl.h : +.Bl -tag -width indent +.It Dv AT_SYMLINK_NOFOLLOW +If +.Fa path +names a symbolic link, ownership of the symbolic link is changed. +.It Dv AT_RESOLVE_BENEATH +Only walk paths below the directory specified by the +.Ar fd +descriptor. +See the description of the +.Dv O_RESOLVE_BENEATH +flag in the +.Xr open 2 +manual page. +.It Dv AT_EMPTY_PATH +If the +.Fa path +argument is an empty string, operate on the file or directory +referenced by the descriptor +.Fa fd . +If +.Fa fd +is equal to +.Dv AT_FDCWD , +operate on the current working directory. +.El +.Pp +If +.Fn fchownat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is identical +to a call to +.Fn chown +or +.Fn lchown +respectively, depending on whether or not the +.Dv AT_SYMLINK_NOFOLLOW +bit is set in the +.Fa flag +argument. +.Pp +One of the owner or group id's +may be left unchanged by specifying it as -1. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn chown +and +.Fn lchown +will fail and the file will be unchanged if: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named file does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EPERM +The operation would change the ownership, but the effective user ID is not the +super-user. +.It Bq Er EPERM +The named file has its immutable or append-only flag set, see the +.Xr chflags 2 +manual page for more information. +.It Bq Er EROFS +The named file resides on a read-only file system. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.El +.Pp +The +.Fn fchown +system call will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument +does not refer to a valid descriptor. +.It Bq Er EINVAL +The +.Fa fd +argument +refers to a socket, not a file. +.It Bq Er EPERM +The effective user ID is not the super-user. +.It Bq Er EROFS +The named file resides on a read-only file system. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.El +.Pp +In addition to the errors specified for +.Fn chown +and +.Fn lchown , +the +.Fn fchownat +system call may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er EINVAL +The value of the +.Fa flag +argument is not valid. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.It Bq Er ENOTCAPABLE +.Fa path +is an absolute path, +or contained a ".." component leading to a +directory outside of the directory hierarchy specified by +.Fa fd , +and the process is in capability mode or the +.Dv AT_RESOLVE_BENEATH +flag was specified. +.El +.Sh SEE ALSO +.Xr chgrp 1 , +.Xr chflags 2 , +.Xr chmod 2 , +.Xr flock 2 , +.Xr chown 8 +.Sh STANDARDS +The +.Fn chown +system call is expected to conform to +.St -p1003.1-90 . +The +.Fn fchownat +system call follows The Open Group Extended API Set 2 specification. +.Sh HISTORY +The +.Fn chown +function appeared in +.At v1 . +The +.Fn fchown +system call appeared in +.Bx 4.2 . +.Pp +The +.Fn chown +system call was changed to follow symbolic links in +.Bx 4.4 . +The +.Fn lchown +system call was added in +.Fx 3.0 +to compensate for the loss of functionality. +.Pp +The +.Fn fchownat +system call appeared in +.Fx 8.0 . diff --git a/lib/libsys/chroot.2 b/lib/libsys/chroot.2 new file mode 100644 index 000000000000..3347df5cceee --- /dev/null +++ b/lib/libsys/chroot.2 @@ -0,0 +1,215 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd August 2, 2025 +.Dt CHROOT 2 +.Os +.Sh NAME +.Nm chroot , +.Nm fchroot +.Nd change root directory +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn chroot "const char *dirname" +.Ft int +.Fn fchroot "int fd" +.Sh DESCRIPTION +The +.Fa dirname +argument +is the address of the pathname of a directory, terminated by an ASCII NUL. +The +.Fn chroot +system call causes +.Fa dirname +to become the root directory, +that is, the starting point for path searches of pathnames +beginning with +.Ql / . +.Pp +In order for a directory to become the root directory +a process must have execute (search) access for that directory. +.Pp +It should be noted that +.Fn chroot +has no effect on the process's current directory. +.Pp +This call is restricted to the super-user, unless the +.Ql security.bsd.unprivileged_chroot +sysctl variable is set to 1 +and the process has enabled the +.Dv PROC_NO_NEW_PRIVS_CTL +.Xr procctl 2 . +.Pp +Depending on the setting of the +.Ql kern.chroot_allow_open_directories +sysctl variable, open filedescriptors which reference directories +will make the +.Fn chroot +fail as follows: +.Pp +If +.Ql kern.chroot_allow_open_directories +is set to zero, +.Fn chroot +will always fail with +.Er EPERM +if there are any directories open. +.Pp +If +.Ql kern.chroot_allow_open_directories +is set to one (the default), +.Fn chroot +will fail with +.Er EPERM +if there are any directories open and the +process is already subject to the +.Fn chroot +system call. +.Pp +Any other value for +.Ql kern.chroot_allow_open_directories +will bypass the check for open directories, +mimicking the historic insecure behavior of +.Fn chroot +still present on other systems. +.Pp +The +.Fn fchroot +system call is identical to +.Fn chroot +except it takes a file descriptor instead of path. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn chroot +and +.Fn fchroot +system calls +will fail and the root directory will be unchanged if: +.Bl -tag -width Er +.It Bq Er EPERM +The effective user ID is not the super-user and the +.Ql security.bsd.unprivileged_chroot +sysctl is 0. +.It Bq Er EPERM +The effective user ID is not the super-user and the +process has not enabled the +.Dv PROC_NO_NEW_PRIVS_CTL +.Xr procctl 2 . +.It Bq Er EPERM +One or more filedescriptors are open directories and the +.Ql kern.chroot_allow_open_directories +sysctl is not set to permit this. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.El +.Pp +The +.Fn chroot +system call +will fail and the root directory will be unchanged if: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path name is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named directory does not exist. +.It Bq Er EACCES +Search permission is denied for any component of the path name. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EFAULT +The +.Fa dirname +argument +points outside the process's allocated address space. +.El +.Pp +The +.Fn fchroot +system call +will fail and the root directory will be unchanged if: +.Bl -tag -width Er +.It Bq Er EACCES +Search permission is denied for the directory referenced by the +file descriptor. +.It Bq Er EBADF +The argument +.Fa fd +is not a valid file descriptor. +.It Bq Er ENOTDIR +The file descriptor does not reference a directory. +.El +.Sh SEE ALSO +.Xr chdir 2 , +.Xr jail 2 +.Sh HISTORY +The +.Fn chroot +system call appeared in +.At v7 . +It was marked as +.Dq legacy +in +.St -susv2 , +and was removed in subsequent standards. +The +.Fn fchroot +system call first appeared in +.Fx 15.0 . +.Sh BUGS +If the process is able to change its working directory to the target +directory, but another access control check fails (such as a check for +open directories, or a MAC check), it is possible that this system +call may return an error, with the working directory of the process +left changed. +.Sh SECURITY CONSIDERATIONS +The system has many hardcoded paths to files which it may load after +the process starts. +It is generally recommended to drop privileges immediately after a +successful +.Nm +call, +and restrict write access to a limited subtree of the +.Nm +root. +For instance, +setup the sandbox so that the sandboxed user will have no write +access to any well-known system directories. +.Pp +For complete isolation from the rest of the system, use +.Xr jail 2 +instead. diff --git a/lib/libsys/clock_gettime.2 b/lib/libsys/clock_gettime.2 new file mode 100644 index 000000000000..89551d0f720b --- /dev/null +++ b/lib/libsys/clock_gettime.2 @@ -0,0 +1,241 @@ +.\" $OpenBSD: clock_gettime.2,v 1.4 1997/05/08 20:21:16 kstailey Exp $ +.\" +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd August 10, 2024 +.Dt CLOCK_GETTIME 2 +.Os +.Sh NAME +.Nm clock_gettime , +.Nm clock_settime , +.Nm clock_getres +.Nd get/set/calibrate date and time +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In time.h +.Ft int +.Fn clock_gettime "clockid_t clock_id" "struct timespec *tp" +.Ft int +.Fn clock_settime "clockid_t clock_id" "const struct timespec *tp" +.Ft int +.Fn clock_getres "clockid_t clock_id" "struct timespec *tp" +.Sh DESCRIPTION +The +.Fn clock_gettime +and +.Fn clock_settime +system calls allow the calling process to retrieve or set the value +used by a clock which is specified by +.Fa clock_id . +.Pp +The +.Fa clock_id +argument can be a value obtained from +.Xr clock_getcpuclockid 3 +or +.Xr pthread_getcpuclockid 3 +as well as the following values: +.Pp +.Bl -tag -width indent -compact +.It Dv CLOCK_REALTIME +.It Dv CLOCK_REALTIME_PRECISE +.It Dv CLOCK_REALTIME_FAST +.It Dv CLOCK_REALTIME_COARSE +Increments in SI seconds like a wall clock. +It uses a 1970 epoch and implements the UTC timescale. +The count of physical SI seconds since 1970, adjusted by subtracting the number +of positive leap seconds and adding the number of negative leap seconds. +Behavior during a leap second is not defined by and POSIX standard. +.It Dv CLOCK_MONOTONIC +.It Dv CLOCK_MONOTONIC_PRECISE +.It Dv CLOCK_MONOTONIC_FAST +.It Dv CLOCK_MONOTONIC_COARSE +.It Dv CLOCK_BOOTTIME +Increments in SI seconds, even while the system is suspended. +Its epoch is unspecified. +The count is not adjusted by leap seconds. +.Fx implements +.It Dv CLOCK_UPTIME +.It Dv CLOCK_UPTIME_PRECISE +.It Dv CLOCK_UPTIME_FAST +Increments monotonically in SI seconds while the machine is running. +The count is not adjusted by leap seconds. +The epoch is unspecified. +.It Dv CLOCK_VIRTUAL +Increments only when +the CPU is running in user mode on behalf of the calling process. +.It Dv CLOCK_PROF +Increments when the CPU is running in user or kernel mode. +.It Dv CLOCK_SECOND +Returns the current second without performing a full time counter +query, using an in-kernel cached value of the current second. +.It Dv CLOCK_PROCESS_CPUTIME_ID +Returns the execution time of the calling process. +.It Dv CLOCK_THREAD_CPUTIME_ID +Returns the execution time of the calling thread. +.It Dv CLOCK_TAI +Increments in SI seconds like a wall clock. +It uses a 1970 epoch and implements the TAI timescale. +Similar to +.Dv CLOCK_REALTIME , +but without leap seconds. +It will increase monotonically during a leap second. +Will return +.Er EINVAL +if the current offset between TAI and UTC is not known, +which may be the case early in boot before NTP or other time daemon has +synchronized. +.El +.Pp +The clock IDs +.Dv CLOCK_BOOTTIME , +.Dv CLOCK_REALTIME , +.Dv CLOCK_TAI , +.Dv CLOCK_MONOTONIC , +and +.Dv CLOCK_UPTIME +perform a full time counter query. +The clock IDs with the _FAST suffix, i.e., +.Dv CLOCK_REALTIME_FAST , +.Dv CLOCK_MONOTONIC_FAST , +and +.Dv CLOCK_UPTIME_FAST , +do not perform +a full time counter query, so their accuracy is one timer tick. +Similarly, +.Dv CLOCK_REALTIME_PRECISE , +.Dv CLOCK_MONOTONIC_PRECISE , +and +.Dv CLOCK_UPTIME_PRECISE +are used to get the most exact value as possible, at the expense of +execution time. +The clock IDs +.Dv CLOCK_REALTIME_COARSE +and +.Dv CLOCK_MONOTONIC_COARSE +are aliases of corresponding IDs with _FAST suffix for compatibility with other +systems. +Finally, +.Dv CLOCK_BOOTTIME +is an alias for +.Dv CLOCK_MONOTONIC +for compatibility with other systems and is unrelated to the +.Fa kern.boottime +.Xr sysctl 8 . +.Pp +The structure pointed to by +.Fa tp +is defined in +.In sys/timespec.h +as: +.Bd -literal +struct timespec { + time_t tv_sec; /* seconds */ + long tv_nsec; /* and nanoseconds */ +}; +.Ed +.Pp +Only the super-user may set the time of day, using only +.Dv CLOCK_REALTIME . +If the system +.Xr securelevel 7 +is greater than 1 (see +.Xr init 8 ) , +the time may only be advanced. +This limitation is imposed to prevent a malicious super-user +from setting arbitrary time stamps on files. +The system time can still be adjusted backwards using the +.Xr adjtime 2 +system call even when the system is secure. +.Pp +The resolution (granularity) of a clock is returned by the +.Fn clock_getres +system call. +This value is placed in a (non-NULL) +.Fa *tp . +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The following error codes may be set in +.Va errno : +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa clock_id +or +.Fa timespec +argument +was not a valid value. +.It Bq Er EPERM +A user other than the super-user attempted to set the time. +.El +.Sh SEE ALSO +.Xr date 1 , +.Xr adjtime 2 , +.Xr clock_getcpuclockid 3 , +.Xr ctime 3 , +.Xr pthread_getcpuclockid 3 +.Sh STANDARDS +The +.Fn clock_gettime , +.Fn clock_settime , +and +.Fn clock_getres +system calls conform to +.St -p1003.1-2008 . +The clock IDs +.Dv CLOCK_BOOTTIME , +.Dv CLOCK_MONOTONIC_FAST , +.Dv CLOCK_MONOTONIC_PRECISE , +.Dv CLOCK_REALTIME_FAST , +.Dv CLOCK_REALTIME_PRECISE , +.Dv CLOCK_SECOND , +.Dv CLOCK_TAI , +.Dv CLOCK_UPTIME , +.Dv CLOCK_UPTIME_FAST , +and +.Dv CLOCK_UPTIME_PRECISE +are +.Fx +extensions to the POSIX interface. +.Pp +UTC is defined by ITU-R TF.460-6, Standard-frequency and time-signal emissions. +However, the +.Vt time_t +type is a simple count that does not provide a unique encoding for leap seconds, +nor a specification for what values should be used to encode a leap second. +.Pp +.Sh HISTORY +The +.Fn clock_gettime , +.Fn clock_settime , +and +.Fn clock_getres +system calls first appeared in +.Fx 3.0 . diff --git a/lib/libsys/clock_gettime.c b/lib/libsys/clock_gettime.c new file mode 100644 index 000000000000..069e70beaa1b --- /dev/null +++ b/lib/libsys/clock_gettime.c @@ -0,0 +1,55 @@ +/*- + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (c) 2012 Konstantin Belousov <kib@FreeBSD.org> + * + * 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. + */ + +#include <sys/syscall.h> +#include <sys/time.h> +#include <sys/vdso.h> +#include <errno.h> +#include <time.h> +#include "libc_private.h" + +int __clock_gettime(clockid_t, struct timespec *ts); + +__weak_reference(__clock_gettime, clock_gettime); + +int +__clock_gettime(clockid_t clock_id, struct timespec *ts) +{ + int error; + + if (__vdso_clock_gettime != NULL && __vdso_gettc != NULL) + error = __vdso_clock_gettime(clock_id, ts); + else + error = ENOSYS; + if (error == ENOSYS) { + error = __sys_clock_gettime(clock_id, ts); + } else if (error != 0) { + errno = error; + error = -1; + } + return (error); +} diff --git a/lib/libsys/close.2 b/lib/libsys/close.2 new file mode 100644 index 000000000000..91a7a902d70d --- /dev/null +++ b/lib/libsys/close.2 @@ -0,0 +1,138 @@ +.\" Copyright (c) 1980, 1991, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd December 18, 2024 +.Dt CLOSE 2 +.Os +.Sh NAME +.Nm close +.Nd delete a descriptor +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn close "int fd" +.Sh DESCRIPTION +The +.Fn close +system call deletes a descriptor from the per-process object +reference table. +If this is the last reference to the underlying object, the +object will be deactivated. +For example, on the last close of a file +the current +.Em seek +pointer associated with the file is lost; +on the last close of a +.Xr socket 2 +associated naming information and queued data are discarded; +on the last close of a file holding an advisory lock +the lock is released (see further +.Xr flock 2 ) . +However, the semantics of System V and +.St -p1003.1-88 +dictate that all +.Xr fcntl 2 +advisory record locks associated with a file for a given process +are removed when +.Em any +file descriptor for that file is closed by that process. +.Pp +When a process exits, +all associated file descriptors are freed, but since there is +a limit on active descriptors per processes, the +.Fn close +system call +is useful when a large quantity of file descriptors are being handled. +.Pp +When a process forks (see +.Xr fork 2 ) , +all descriptors for the new child process reference the same +objects as they did in the parent before the fork. +If a new process is then to be run using +.Xr execve 2 , +the process would normally inherit these descriptors. +Most +of the descriptors can be rearranged with +.Xr dup2 2 +or deleted with +.Fn close +before the +.Xr execve 2 +is attempted, but if some of these descriptors will still +be needed if the execve fails, it is necessary to arrange for them +to be closed if the execve succeeds. +For this reason, the call +.Dq Li fcntl(d, F_SETFD, FD_CLOEXEC) +is provided, +which arranges that a descriptor will be closed after a successful +execve; the call +.Dq Li fcntl(d, F_SETFD, 0) +restores the default, +which is to not close the descriptor. +.Sh RETURN VALUES +.Rv -std close +.Sh ERRORS +The +.Fn close +system call will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument +is not an active descriptor. +.It Bq Er EINTR +An interrupt was received. +.It Bq Er ENOSPC +The underlying object did not fit, cached data was lost. +.El +.Pp +In case of any error except +.Er EBADF , +the supplied file descriptor is deallocated and therefore is no longer valid. +.Sh SEE ALSO +.Xr accept 2 , +.Xr closefrom 2 , +.Xr execve 2 , +.Xr fcntl 2 , +.Xr flock 2 , +.Xr open 2 , +.Xr pipe 2 , +.Xr socket 2 , +.Xr socketpair 2 +.Sh STANDARDS +The +.Fn close +system call is expected to conform to +.St -p1003.1-90 . +.Sh HISTORY +The +.Fn close +function appeared in +.At v1 . diff --git a/lib/libsys/closefrom.2 b/lib/libsys/closefrom.2 new file mode 100644 index 000000000000..1885a6fdeaa8 --- /dev/null +++ b/lib/libsys/closefrom.2 @@ -0,0 +1,99 @@ +.\" Copyright (c) 2009 Hudson River Trading LLC +.\" Written by: John H. Baldwin <jhb@FreeBSD.org> +.\" All rights reserved. +.\" +.\" 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. +.\" +.Dd May 17, 2025 +.Dt CLOSEFROM 2 +.Os +.Sh NAME +.Nm closefrom , +.Nm close_range +.Nd delete open file descriptors +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft void +.Fn closefrom "int lowfd" +.Ft int +.Fn close_range "u_int lowfd" "u_int highfd" "int flags" +.Sh DESCRIPTION +The +.Fn closefrom +system call deletes all open file descriptors greater than or equal to +.Fa lowfd +from the per-process object reference table. +Any errors encountered while closing file descriptors are ignored. +.Pp +The +.Fn close_range +system call deletes all open file descriptors between +.Fa lowfd +and +.Fa highfd +inclusive, clamped to the range of open file descriptors. +Any errors encountered while closing file descriptors are ignored. +Supported +.Fa flags : +.Bl -tag -width ".Dv CLOSE_RANGE_CLOEXEC" +.It Dv CLOSE_RANGE_CLOEXEC +Set the close-on-exec flag on descriptors in the range instead of closing them. +.It Dv CLOSE_RANGE_CLOFORK +Set the close-on-fork flag on descriptors in the range instead of closing them. +.El +.Sh RETURN VALUES +Upon successful completion, +.Fn close_range +returns a value +of 0. +Otherwise, a value of -1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn close_range +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa highfd +argument is lower than the +.Fa lowfd +argument. +.It Bq Er EINVAL +An invalid flag was set. +.El +.Sh SEE ALSO +.Xr close 2 +.Sh HISTORY +The +.Fn closefrom +function first appeared in +.Fx 8.0 . +.Pp +The +.Dv CLOSE_RANGE_CLOFORK +flag appeared in +.Fx 15.0 . diff --git a/lib/libsys/connect.2 b/lib/libsys/connect.2 new file mode 100644 index 000000000000..ac36cf8b15b3 --- /dev/null +++ b/lib/libsys/connect.2 @@ -0,0 +1,182 @@ +.\" Copyright (c) 1983, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd August 18, 2016 +.Dt CONNECT 2 +.Os +.Sh NAME +.Nm connect +.Nd initiate a connection on a socket +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/socket.h +.Ft int +.Fn connect "int s" "const struct sockaddr *name" "socklen_t namelen" +.Sh DESCRIPTION +The +.Fa s +argument +is a socket. +If it is of type +.Dv SOCK_DGRAM , +this call specifies the peer with which the socket is to be associated; +this address is that to which datagrams are to be sent, +and the only address from which datagrams are to be received. +If the socket is of type +.Dv SOCK_STREAM , +this call attempts to make a connection to +another socket. +The other socket is specified by +.Fa name , +which is an address in the communications space of the socket. +.Fa namelen +indicates the amount of space pointed to by +.Fa name , +in bytes; the +.Fa sa_len +member of +.Fa name +is ignored. +Each communications space interprets the +.Fa name +argument in its own way. +Generally, stream sockets may successfully +.Fn connect +only once; datagram sockets may use +.Fn connect +multiple times to change their association. +Datagram sockets may dissolve the association +by connecting to an invalid address, such as a null address. +.Sh RETURN VALUES +.Rv -std connect +.Sh ERRORS +The +.Fn connect +system call fails if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa s +argument +is not a valid descriptor. +.It Bq Er EINVAL +The +.Fa namelen +argument is not a valid length for the address family. +.It Bq Er ENOTSOCK +The +.Fa s +argument +is a descriptor for a file, not a socket. +.It Bq Er EADDRNOTAVAIL +The specified address is not available on this machine. +.It Bq Er EAFNOSUPPORT +Addresses in the specified address family cannot be used with this socket. +.It Bq Er EISCONN +The socket is already connected. +.It Bq Er ETIMEDOUT +Connection establishment timed out without establishing a connection. +.It Bq Er ECONNREFUSED +The attempt to connect was forcefully rejected. +.It Bq Er ECONNRESET +The connection was reset by the remote host. +.It Bq Er ENETUNREACH +The network is not reachable from this host. +.It Bq Er EHOSTUNREACH +The remote host is not reachable from this host. +.It Bq Er EADDRINUSE +The address is already in use. +.It Bq Er EFAULT +The +.Fa name +argument specifies an area outside +the process address space. +.It Bq Er EINPROGRESS +The socket is non-blocking +and the connection cannot +be completed immediately. +It is possible to +.Xr select 2 +for completion by selecting the socket for writing. +.It Bq Er EINTR +The connection attempt was interrupted by the delivery of a signal. +The connection will be established in the background, +as in the case of +.Er EINPROGRESS . +.It Bq Er EALREADY +A previous connection attempt has not yet been completed. +.It Bq Er EACCES +An attempt is made to connect to a broadcast address (obtained through the +.Dv INADDR_BROADCAST +constant or the +.Dv INADDR_NONE +return value) through a socket that does not provide broadcast functionality. +.It Bq Er EAGAIN +An auto-assigned port number was requested but no auto-assigned ports +are available. +Increasing the port range specified by +.Xr sysctl 3 +MIB variables +.Va net.inet.ip.portrange.first +and +.Va net.inet.ip.portrange.last +may alleviate the problem. +.El +.Pp +The following errors are specific to connecting names in the UNIX domain. +These errors may not apply in future versions of the UNIX IPC domain. +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named socket does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er EACCES +Write access to the named socket is denied. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EPERM +Write access to the named socket is denied. +.El +.Sh SEE ALSO +.Xr accept 2 , +.Xr getpeername 2 , +.Xr getsockname 2 , +.Xr select 2 , +.Xr socket 2 , +.Xr sysctl 3 , +.Xr sysctl 8 +.Sh HISTORY +The +.Fn connect +system call appeared in +.Bx 4.2 . diff --git a/lib/libsys/connectat.2 b/lib/libsys/connectat.2 new file mode 100644 index 000000000000..64fd805549b7 --- /dev/null +++ b/lib/libsys/connectat.2 @@ -0,0 +1,106 @@ +.\" Copyright (c) 2013 The FreeBSD Foundation +.\" +.\" This documentation was written by Pawel Jakub Dawidek under sponsorship from +.\" the FreeBSD Foundation. +.\" +.\" 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 AUTHORS 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 AUTHORS 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. +.\" +.Dd February 13, 2013 +.Dt CONNECTAT 2 +.Os +.Sh NAME +.Nm connectat +.Nd initiate a connection on a socket +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.Pp +.In fcntl.h +.Ft int +.Fn connectat "int fd" "int s" "const struct sockaddr *name" "socklen_t namelen" +.Sh DESCRIPTION +The +.Fn connectat +system call initiates a connection on the socket +.Fa s . +When passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the behavior is identical to a call to +.Xr connect 2 . +Otherwise, +.Fn connectat +works like the +.Xr connect 2 +system call with two exceptions: +.Pp +.Bl -enum -offset indent -compact +.It +It is limited to sockets in the PF_LOCAL domain. +.Pp +.It +If the file path stored in the +.Fa sun_path +field of the sockaddr_un structure is a relative path, it is located relative +to the directory associated with the file descriptor +.Fa fd . +.El +.Sh RETURN VALUES +.Rv -std connectat +.Sh ERRORS +The +.Fn connectat +system call may fail with the same errors as the +.Xr connect 2 +system call or with the following errors: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa sun_path +field does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor. +.It Bq Er ENOTDIR +The +.Fa sun_path +field is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El +.Sh SEE ALSO +.Xr bindat 2 , +.Xr connect 2 , +.Xr socket 2 , +.Xr unix 4 +.Sh AUTHORS +The +.Nm +was developed by +.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net +under sponsorship from the FreeBSD Foundation. diff --git a/lib/libsys/copy_file_range.2 b/lib/libsys/copy_file_range.2 new file mode 100644 index 000000000000..bcd9170842d5 --- /dev/null +++ b/lib/libsys/copy_file_range.2 @@ -0,0 +1,218 @@ +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2019 Rick Macklem +.\" +.\" 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. +.\" +.Dd December 28, 2023 +.Dt COPY_FILE_RANGE 2 +.Os +.Sh NAME +.Nm copy_file_range +.Nd kernel copy of a byte range from one regular file to another +or within one regular file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In unistd.h +.Ft ssize_t +.Fo copy_file_range +.Fa "int infd" +.Fa "off_t *inoffp" +.Fa "int outfd" +.Fa "off_t *outoffp" +.Fa "size_t len" +.Fa "unsigned int flags" +.Fc +.Sh DESCRIPTION +The +.Fn copy_file_range +system call +copies up to +.Fa len +bytes from +.Fa infd +to +.Fa outfd +in the kernel. +It may do this using a file system specific technique if +.Fa infd +and +.Fa outfd +are on the same file system. +If +.Fa infd +and +.Fa outfd +refer to the same file, the byte ranges defined by +the input file offset, output file offset and +.Fa len +cannot overlap. +The +.Fa infd +argument must be opened for reading and the +.Fa outfd +argument must be opened for writing, but not +.Dv O_APPEND . +If +.Fa inoffp +or +.Fa outoffp +is +.Dv NULL , +the file offset for +.Fa infd +or +.Fa outfd +respectively will be used and updated by +the number of bytes copied. +If +.Fa inoffp +or +.Fa outoffp +is not +.Dv NULL , +the byte offset pointed to by +.Fa inoffp +or +.Fa outoffp +respectively will be used/updated and the file offset for +.Fa infd +or +.Fa outfd +respectively will not be affected. +The +.Fa flags +argument must be 0. +.Pp +This system call attempts to maintain holes in the output file for +the byte range being copied. +However, this does not always work well. +It is recommended that sparse files be copied in a loop using +.Xr lseek 2 +with +.Dv SEEK_HOLE , +.Dv SEEK_DATA +arguments and this system call for the +data ranges found. +.Pp +For best performance, call +.Fn copy_file_range +with the largest +.Fa len +value possible. +It is interruptible on most file systems, +so there is no penalty for using very large len values, even SSIZE_MAX. +.Pp +.Sh RETURN VALUES +If it succeeds, the call returns the number of bytes copied, which can be fewer +than +.Fa len . +Returning fewer bytes than +.Fa len +does not necessarily indicate that EOF was reached. +However, a return of zero for a non-zero +.Fa len +argument indicates that the offset for +.Fa infd +is at or beyond EOF. +.Fn copy_file_range +should be used in a loop until copying of the desired byte range has been +completed. +If an error has occurred, a \-1 is returned and the error code is placed in +the global variable +.Va errno . +.Sh ERRORS +The +.Fn copy_file_range +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +If +.Fa infd +is not open for reading or +.Fa outfd +is not open for writing, or opened for writing with +.Dv O_APPEND , +or if +.Fa infd +and +.Fa outfd +refer to the same file. +.It Bq Er EFBIG +If the copy exceeds the process's file size limit or the maximum file size +for the file system +.Fa outfd +resides on. +.It Bq Er EINTR +A signal interrupted the system call +before it could be completed. +This may happen for files on some NFS mounts. +When this happens, the values pointed to by +.Fa inoffp +and +.Fa outoffp +are reset to the initial values for the system call. +.It Bq Er EINVAL +.Fa infd +and +.Fa outfd +refer to the same file and the byte ranges overlap. +.It Bq Er EINVAL +The +.Fa flags +argument is not zero. +.It Bq Er EINVAL +Either +.Fa infd +or +.Fa outfd +refers to a file object that is not a regular file. +.It Bq Er EIO +An I/O error occurred while reading/writing the files. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from a file system. +.It Bq Er EISDIR +If either +.Fa infd +or +.Fa outfd +refers to a directory. +.It Bq Er ENOSPC +File system that stores +.Fa outfd +is full. +.El +.Sh SEE ALSO +.Xr lseek 2 +.Sh STANDARDS +The +.Fn copy_file_range +system call is expected to be compatible with the Linux system call of +the same name. +.Sh HISTORY +The +.Fn copy_file_range +function appeared in +.Fx 13.0 . diff --git a/lib/libsys/cpuset.2 b/lib/libsys/cpuset.2 new file mode 100644 index 000000000000..3d47f1b4fdfb --- /dev/null +++ b/lib/libsys/cpuset.2 @@ -0,0 +1,302 @@ +.\" Copyright (c) 2008 Christian Brueffer +.\" Copyright (c) 2008 Jeffrey Roberson +.\" Copyright (c) 2021 Robert N. M. Watson +.\" All rights reserved. +.\" +.\" 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. +.\" +.Dd January 29, 2023 +.Dt CPUSET 2 +.Os +.Sh NAME +.Nm cpuset , +.Nm cpuset_getid , +.Nm cpuset_setid +.Nd manage CPU affinity sets +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/cpuset.h +.Ft int +.Fn cpuset "cpusetid_t *setid" +.Ft int +.Fn cpuset_setid "cpuwhich_t which" "id_t id" "cpusetid_t setid" +.Ft int +.Fn cpuset_getid "cpulevel_t level" "cpuwhich_t which" "id_t id" "cpusetid_t *setid" +.Sh DESCRIPTION +The +.Nm +family of system calls allow applications to control sets of processors and +memory domains and assign processes and threads to these sets. +Processor sets contain lists of CPUs and domains that members may run on +and exist only as long as some process is a member of the set. +All processes in the system have an assigned set. +The default set for all processes in the system is the set numbered 1. +Threads belong to the same set as the process which contains them, +however, they may further restrict their set with the anonymous +per-thread mask to bind to a specific CPU or subset of CPUs and memory domains. +.Pp +Sets are referenced by a number of type +.Ft cpuset_id_t . +Each thread has a root set, an assigned set, and an anonymous mask. +Only the root and assigned sets are numbered. +The root set is the set of all CPUs and memory domains available in the system +or in the system partition the thread is running in. +The assigned set is a subset of the root set and is administratively +assignable on a per-process basis. +Many processes and threads may be members of a numbered set. +.Pp +The anonymous set is a further thread-specific refinement on the assigned +set. +It is intended that administrators will manipulate numbered sets using +.Xr cpuset 1 +while application developers will manipulate anonymous sets using +.Xr cpuset_setaffinity 2 and +.Xr cpuset_setdomain 2 . +.Pp +To select the correct set a value of type +.Ft cpulevel_t +is used. +The following values for +.Fa level +are supported: +.Bl -column CPU_LEVEL_CPUSET -offset indent +.It Dv CPU_LEVEL_ROOT Ta "Root set" +.It Dv CPU_LEVEL_CPUSET Ta "Assigned set" +.It Dv CPU_LEVEL_WHICH Ta "Set specified by which argument" +.El +.Pp +The +.Fa which +argument determines how the value of +.Fa id +is interpreted and is of type +.Ft cpuwhich_t . +The +.Fa which +argument may have the following values: +.Bl -column CPU_WHICH_INTRHANDLER -offset indent +.It Dv CPU_WHICH_TID Ta "id is lwpid_t (thread id)" +.It Dv CPU_WHICH_PID Ta "id is pid_t (process id)" +.It Dv CPU_WHICH_TIDPID Ta "id is either a thread or process id" +.It Dv CPU_WHICH_JAIL Ta "id is jid (jail id)" +.It Dv CPU_WHICH_CPUSET Ta "id is a cpusetid_t (cpuset id)" +.It Dv CPU_WHICH_IRQ Ta "id is an irq number" +.It Dv CPU_WHICH_INTRHANDLER Ta "id is an irq number for an interrupt handler" +.It Dv CPU_WHICH_ITHREAD Ta "id is an irq number for an ithread" +.It Dv CPU_WHICH_DOMAIN Ta "id is a NUMA domain" +.El +.Pp +An +.Fa id +of '-1' may be used with a +.Fa which +of +.Dv CPU_WHICH_TID , +.Dv CPU_WHICH_PID , +.Dv CPU_WHICH_TIDPID , +or +.Dv CPU_WHICH_CPUSET +to mean the current thread, process, or current thread's +cpuset. +All cpuset syscalls allow this usage. +.Pp +A +.Fa level +argument of +.Dv CPU_LEVEL_WHICH +combined with a +.Fa which +argument other than +.Dv CPU_WHICH_CPUSET +refers to the anonymous mask of the object. +This mask does not have an id and may only be manipulated with +.Xr cpuset_setaffinity 2 . +.Pp +.Fn cpuset +creates a new set containing the same CPUs as the root set of the current +process and stores its id in the space provided by +.Fa setid . +On successful completion the calling process joins the set and is the +only member. +Children inherit this set after a call to +.Xr fork 2 . +.Pp +.Fn cpuset_setid +attempts to set the id of the object specified by the +.Fa which +argument. +Currently +.Dv CPU_WHICH_PID +is the only acceptable value for which as +threads do not have an id distinct from their process and the API does +not permit changing the id of an existing set. +Upon successful completion all of the threads in the target process will +be running on CPUs permitted by the set. +.Pp +.Fn cpuset_getid +retrieves a set id from the object indicated by +.Fa which +and stores it in the space pointed to by +.Fa setid . +The retrieved id may be that of either the root or assigned set +depending on the value of +.Fa level . +.Fa level +should be +.Dv CPU_LEVEL_CPUSET +or +.Dv CPU_LEVEL_ROOT +to get the set id from +the process or thread specified by the +.Fa id +argument. +Specifying +.Dv CPU_LEVEL_WHICH +with a process or thread is unsupported since +this references the unnumbered anonymous mask. +.Pp +The actual contents of the sets may be retrieved or manipulated using +.Xr cpuset_getaffinity 2 , +.Xr cpuset_setaffinity 2 , +.Xr cpuset_getdomain 2 , and +.Xr cpuset_setdomain 2 . +The +.Xr cpuset 9 +macros may be used to manipulate masks of type +.Ft cpuset_t +get and set using those APIs. +See those manual pages for more detail. +.Sh RETURN VALUES +.Rv -std +.Sh EXAMPLES +In this example, a CPU set mask is configured to limit execution to the first +CPU using +.Xr CPU_ZERO 9 +and +.Xr CPU_SET 9 , +members of the +.Xr cpuset 9 +programming interface. +Then, the mask is applied to a new anonymous CPU set associated with the +current process using +.Xr cpuset_setaffinity 2 . +This mask will be used by the current process, and inherited by any new +child processes. +.Bd -literal -offset indent +#include <sys/param.h> +#include <sys/cpuset.h> + +#include <sysexits.h> + +cpuset_t cpuset_mask; + +/* Initialize a CPU mask and enable CPU 0. */ +CPU_ZERO(&cpuset_mask); +CPU_SET(0, &cpuset_mask); + +/* Set affinity for the CPU set for the current process. */ +if (cpuset_setaffinity(CPU_LEVEL_WHICH, CPU_WHICH_PID, -1, + sizeof(cpuset_mask), &cpuset_mask) < 0) + err(EX_OSERR, "cpuset_setaffinity"); +.Ed +.Pp +In the next example, a named CPU set is created containing the current +process, and its affinity similarly configured. +The resulting CPU set ID can then be used for further external management of +the affinity of the set. +.Bd -literal -offset indent +#include <sys/param.h> +#include <sys/cpuset.h> + +#include <sysexits.h> + +cpusetid_t cpuset_id; +cpuset_t cpuset_mask; + +/* Create new cpuset for the current process. */ +if (cpuset(&cpuset_id) < 0) + err(EX_OSERR, "cpuset"); + +/* Initialize a CPU mask and enable CPU 0. */ +CPU_ZERO(&cpuset_mask); +CPU_SET(0, &cpuset_mask); + +/* Set affinity for the CPU set for the current process. */ +if (cpuset_setaffinity(CPU_LEVEL_SET, CPU_WHICH_CPUSET, cpuset_id, + sizeof(cpuset_mask), &cpuset_mask) < 0) + err(EX_OSERR, "cpuset_setaffinity"); +.Ed +.Sh ERRORS +The following error codes may be set in +.Va errno : +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa which +or +.Fa level +argument was not a valid value. +.It Bq Er EDEADLK +The +.Fn cpuset_setid +call would leave a thread without a valid CPU to run on because the set +does not overlap with the thread's anonymous mask. +.It Bq Er EFAULT +The setid pointer passed to +.Fn cpuset_getid +or +.Fn cpuset +was invalid. +.It Bq Er ESRCH +The object specified by the +.Fa id +and +.Fa which +arguments could not be found. +.It Bq Er EPERM +The calling process did not have the credentials required to complete the +operation. +.It Bq Er ENFILE +There was no free +.Ft cpusetid_t +for allocation. +.El +.Sh SEE ALSO +.Xr cpuset 1 , +.Xr cpuset_getaffinity 2 , +.Xr cpuset_getdomain 2 , +.Xr cpuset_setaffinity 2 , +.Xr cpuset_setdomain 2 , +.Xr pthread_affinity_np 3 , +.Xr pthread_attr_affinity_np 3 , +.Xr CPU_SET 9 , +.Xr CPU_ZERO 9 , +.Xr cpuset 9 +.Sh HISTORY +The +.Nm +family of system calls first appeared in +.Fx 7.1 . +.Sh AUTHORS +.An Jeffrey Roberson Aq Mt jeff@FreeBSD.org diff --git a/lib/libsys/cpuset_getaffinity.2 b/lib/libsys/cpuset_getaffinity.2 new file mode 100644 index 000000000000..850ec2a28e03 --- /dev/null +++ b/lib/libsys/cpuset_getaffinity.2 @@ -0,0 +1,177 @@ +.\" Copyright (c) 2008 Christian Brueffer +.\" Copyright (c) 2008 Jeffrey Roberson +.\" All rights reserved. +.\" +.\" 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. +.\" +.Dd April 27, 2022 +.Dt CPUSET_GETAFFINITY 2 +.Os +.Sh NAME +.Nm cpuset_getaffinity , +.Nm cpuset_setaffinity +.Nd manage CPU affinity +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/cpuset.h +.Ft int +.Fn cpuset_getaffinity "cpulevel_t level" "cpuwhich_t which" "id_t id" "size_t setsize" "cpuset_t *mask" +.Ft int +.Fn cpuset_setaffinity "cpulevel_t level" "cpuwhich_t which" "id_t id" "size_t setsize" "const cpuset_t *mask" +.Sh DESCRIPTION +.Fn cpuset_getaffinity +and +.Fn cpuset_setaffinity +allow the manipulation of sets of CPUs available to processes, threads, +interrupts, jails and other resources. +These functions may manipulate sets of CPUs that contain many processes +or per-object anonymous masks that effect only a single object. +.Pp +The valid values for the +.Fa level +and +.Fa which +arguments are documented in +.Xr cpuset 2 . +These arguments specify which object and which set of the object we are +referring to. +Not all possible combinations are valid. +For example, only processes may belong to a numbered set accessed by a +.Fa level +argument of +.Dv CPU_LEVEL_CPUSET . +All resources, however, have a mask which may be manipulated with +.Dv CPU_LEVEL_WHICH . +.Pp +Masks of type +.Ft cpuset_t +are composed using the +.Dv CPU_SET +macros. +If the user-supplied mask is not large enough to fit all of the matching CPUs, +.Fn cpuset_getaffinity +fails with +.Er ERANGE . +Calls to +.Fn cpuset_setaffinity +tolerate masks of any size with no restrictions. +The kernel uses the meaningful part of the mask, where the upper bound is +the maximum CPU id present in the system. +If bits for non-existing CPUs are set, calls to +.Fn cpuset_setaffinity +fail with +.Er EINVAL . +.Pp +The supplied mask should have a size of +.Fa setsize +bytes. +This size is usually provided by calling +.Li sizeof(mask) +which is ultimately determined by the value of +.Dv CPU_SETSIZE +as defined in +.In sys/cpuset.h . +.Pp +.Fn cpuset_getaffinity +retrieves the +mask from the object specified by +.Fa level , +.Fa which +and +.Fa id +and stores it in the space provided by +.Fa mask . +.Pp +.Fn cpuset_setaffinity +attempts to set the mask for the object specified by +.Fa level , +.Fa which +and +.Fa id +to the value in +.Fa mask . +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The following error codes may be set in +.Va errno : +.Bl -tag -width Er +.\" When changing this list, consider updating share/man/man3/pthread_create.3, +.\" since that function can return any of these errors. +.It Bq Er EINVAL +The +.Fa level +or +.Fa which +argument was not a valid value. +.It Bq Er EINVAL +The +.Fa mask +argument specified when calling +.Fn cpuset_setaffinity +was not a valid value. +.It Bq Er EDEADLK +The +.Fn cpuset_setaffinity +call would leave a thread without a valid CPU to run on because the set +does not overlap with the thread's anonymous mask. +.It Bq Er EFAULT +The mask pointer passed was invalid. +.It Bq Er ESRCH +The object specified by the +.Fa id +and +.Fa which +arguments could not be found. +.It Bq Er ERANGE +The +.Fa cpusetsize +was smaller than needed to fit all of the matching CPUs. +.It Bq Er EPERM +The calling process did not have the credentials required to complete the +operation. +.It Bq Er ECAPMODE +The calling process attempted to act on a process other than itself, while +in capability mode. +See +.Xr capsicum 4 . +.El +.Sh SEE ALSO +.Xr cpuset 1 , +.Xr cpuset 2 , +.Xr cpuset_getdomain 2 , +.Xr cpuset_getid 2 , +.Xr cpuset_setdomain 2 , +.Xr cpuset_setid 2 , +.Xr pthread_affinity_np 3 , +.Xr pthread_attr_affinity_np 3 , +.Xr capsicum 4 , +.Xr cpuset 9 +.Sh HISTORY +The +.Nm +family of system calls first appeared in +.Fx 7.1 . +.Sh AUTHORS +.An Jeffrey Roberson Aq Mt jeff@FreeBSD.org diff --git a/lib/libsys/cpuset_getdomain.2 b/lib/libsys/cpuset_getdomain.2 new file mode 100644 index 000000000000..e082dc98939d --- /dev/null +++ b/lib/libsys/cpuset_getdomain.2 @@ -0,0 +1,189 @@ +.\" Copyright (c) 2018 Jeffrey Roberson +.\" All rights reserved. +.\" +.\" 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. +.\" +.Dd June 18, 2020 +.Dt CPUSET_GETDOMAIN 2 +.Os +.Sh NAME +.Nm cpuset_getdomain , +.Nm cpuset_setdomain +.Nd manage memory domain policy +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/domainset.h +.Ft int +.Fn cpuset_getdomain "cpulevel_t level" "cpuwhich_t which" "id_t id" "size_t setsize" "domainset_t *mask" "int *policy" +.Ft int +.Fn cpuset_setdomain "cpulevel_t level" "cpuwhich_t which" "id_t id" "size_t setsize" "const domainset_t *mask" "int policy" +.Sh DESCRIPTION +.Fn cpuset_getdomain +and +.Fn cpuset_setdomain +allow the manipulation of sets of memory domains and allocation policy available +to processes, threads, jails and other resources. +These functions may manipulate sets of memory domains that contain many processes +or per-object anonymous masks that affect only a single object. +.Pp +The valid values for the +.Fa level +and +.Fa which +arguments are documented in +.Xr cpuset 2 . +These arguments specify which object and which set of the object we are +referring to. +Not all possible combinations are valid. +For example, only processes may belong to a numbered set accessed by a +.Fa level +argument of +.Dv CPU_LEVEL_CPUSET . +All resources, however, have a mask which may be manipulated with +.Dv CPU_LEVEL_WHICH . +.Pp +Masks of type +.Ft domainset_t +are composed using the +.Dv DOMAINSET +macros. +The kernel tolerates large sets as long as all domains specified +in the set exist. +Sets smaller than the kernel uses generate an error on calls to +.Fn cpuset_getdomain +even if the result set would fit within the user supplied set. +Calls to +.Fn cpuset_setdomain +tolerate small sets with no restrictions. +.Pp +The supplied mask should have a size of +.Fa setsize +bytes. +This size is usually provided by calling +.Li sizeof(mask) +which is ultimately determined by the value of +.Dv DOMAINSET_SETSIZE +as defined in +.In sys/domainset.h . +.Pp +.Fn cpuset_getdomain +retrieves the +mask and policy from the object specified by +.Fa level , +.Fa which +and +.Fa id +and stores it in the space provided by +.Fa mask +and +.Fa policy . +.Pp +.Fn cpuset_setdomain +attempts to set the mask and policy for the object specified by +.Fa level , +.Fa which +and +.Fa id +to the values in +.Fa mask +and +.Fa policy . +.Sh ALLOCATION POLICIES +Valid policy values are as follows: +.Bl -tag -width "foo" +.It Dv DOMAINSET_POLICY_ROUNDROBIN +Memory is allocated on a round-robin basis by cycling through each domain in +.Fa mask . +.It Dv DOMAINSET_POLICY_FIRSTTOUCH +Memory is allocated on the domain local to the CPU the requesting thread is +running on. +Failure to allocate from this domain will fallback to round-robin. +.It Dv DOMAINSET_POLICY_PREFER +Memory is allocated preferentially from the single domain specified in the mask. +If memory is unavailable the domains listed in the parent cpuset will be +visited in a round-robin order. +.El +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The following error codes may be set in +.Va errno : +.Bl -tag -width Er +.\" When changing this list, consider updating share/man/man3/pthread_create.3, +.\" since that function can return any of these errors. +.It Bq Er EINVAL +The +.Fa level +or +.Fa which +argument was not a valid value. +.It Bq Er EINVAL +The +.Fa mask or +.Fa policy +argument specified when calling +.Fn cpuset_setdomain +was not a valid value. +.It Bq Er EDEADLK +The +.Fn cpuset_setdomain +call would leave a thread without a valid CPU to run on because the set +does not overlap with the thread's anonymous mask. +.It Bq Er EFAULT +The mask pointer passed was invalid. +.It Bq Er ESRCH +The object specified by the +.Fa id +and +.Fa which +arguments could not be found. +.It Bq Er ERANGE +The +.Fa domainsetsize +was either preposterously large or smaller than the kernel set size. +.It Bq Er EPERM +The calling process did not have the credentials required to complete the +operation. +.It Bq Er ECAPMODE +The calling process attempted to act on a process other than itself, while +in capability mode. +See +.Xr capsicum 4 . +.El +.Sh SEE ALSO +.Xr cpuset 1 , +.Xr cpuset 2 , +.Xr cpuset_getaffinity 2 , +.Xr cpuset_getid 2 , +.Xr cpuset_setaffinity 2 , +.Xr cpuset_setid 2 , +.Xr capsicum 4 , +.Xr cpuset 9 +.Sh HISTORY +The +.Nm +family of system calls first appeared in +.Fx 12.0 . +.Sh AUTHORS +.An Jeffrey Roberson Aq Mt jeff@FreeBSD.org diff --git a/lib/libsys/creat.2 b/lib/libsys/creat.2 new file mode 100644 index 000000000000..c15c68e445c0 --- /dev/null +++ b/lib/libsys/creat.2 @@ -0,0 +1,59 @@ +.\" Copyright (c) 1989, 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd September 4, 2019 +.Dt CREAT 2 +.Os +.Sh NAME +.Nm creat +.Nd create a new file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In fcntl.h +.Ft int +.Fn creat "const char *path" "mode_t mode" +.Sh DESCRIPTION +.Bf -symbolic +This interface is made obsolete by: +.Ef +.Xr open 2 . +.Pp +The +.Fn creat +function +is the same as: +.Bd -literal -offset indent +open(path, O_CREAT | O_TRUNC | O_WRONLY, mode); +.Ed +.Sh SEE ALSO +.Xr open 2 +.Sh HISTORY +The +.Fn creat +function appeared in +.At v1 . diff --git a/lib/libsys/dup.2 b/lib/libsys/dup.2 new file mode 100644 index 000000000000..524fd7688670 --- /dev/null +++ b/lib/libsys/dup.2 @@ -0,0 +1,168 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd December 1, 2017 +.Dt DUP 2 +.Os +.Sh NAME +.Nm dup , +.Nm dup2 +.Nd duplicate an existing file descriptor +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn dup "int oldd" +.Ft int +.Fn dup2 "int oldd" "int newd" +.Sh DESCRIPTION +The +.Fn dup +system call +duplicates an existing object descriptor and returns its value to +the calling process +.Fa ( newd += +.Fn dup oldd ) . +The argument +.Fa oldd +is a small non-negative integer index in +the per-process descriptor table. +The new descriptor returned by the call +is the lowest numbered descriptor +currently not in use by the process. +.Pp +The object referenced by the descriptor does not distinguish +between +.Fa oldd +and +.Fa newd +in any way. +Thus if +.Fa newd +and +.Fa oldd +are duplicate references to an open +file, +.Xr read 2 , +.Xr write 2 +and +.Xr lseek 2 +calls all move a single pointer into the file, +and append mode, non-blocking I/O and asynchronous I/O options +are shared between the references. +If a separate pointer into the file is desired, a different +object reference to the file must be obtained by issuing an +additional +.Xr open 2 +system call. +The close-on-exec flag on the new file descriptor is unset. +.Pp +In +.Fn dup2 , +the value of the new descriptor +.Fa newd +is specified. +If this descriptor is already in use and +.Fa oldd +\*(Ne +.Fa newd , +the descriptor is first deallocated as if the +.Xr close 2 +system call had been used. +If +.Fa oldd +is not a valid descriptor, then +.Fa newd +is not closed. +If +.Fa oldd +== +.Fa newd +and +.Fa oldd +is a valid descriptor, then +.Fn dup2 +is successful, and does nothing. +.Sh RETURN VALUES +These calls return the new file descriptor if successful; +otherwise the value -1 is returned and +the external variable +.Va errno +is set to indicate the cause of the error. +.Sh ERRORS +The +.Fn dup +system call fails if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa oldd +argument +is not a valid active descriptor +.It Bq Er EMFILE +Too many descriptors are active. +.El +.Pp +The +.Fn dup2 +system call fails if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa oldd +argument is not a valid active descriptor or the +.Fa newd +argument is negative or exceeds the maximum allowable descriptor number +.El +.Sh SEE ALSO +.Xr accept 2 , +.Xr close 2 , +.Xr fcntl 2 , +.Xr getdtablesize 2 , +.Xr open 2 , +.Xr pipe 2 , +.Xr socket 2 , +.Xr socketpair 2 , +.Xr dup3 3 +.Sh STANDARDS +The +.Fn dup +and +.Fn dup2 +system calls are expected to conform to +.St -p1003.1-90 . +.Sh HISTORY +The +.Fn dup +function appeared in +.At v3 . +The +.Fn dup2 +function appeared in +.At v7 . diff --git a/lib/libsys/eventfd.2 b/lib/libsys/eventfd.2 new file mode 100644 index 000000000000..d472b48f1daa --- /dev/null +++ b/lib/libsys/eventfd.2 @@ -0,0 +1,206 @@ +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2020 Val Packett <val@packett.cool> +.\" +.\" 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. +.\" +.Dd October 8, 2020 +.Dt EVENTFD 2 +.Os +.Sh NAME +.Nm eventfd +.Nd create a file descriptor for event notification +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/eventfd.h +.Ft int +.Fn eventfd "unsigned int initval" "int flags" +.Ft int +.Fn eventfd_read "int fd" "eventfd_t *value" +.Ft int +.Fn eventfd_write "int fd" "eventfd_t value" +.Sh DESCRIPTION +.Fn eventfd +creates a special file descriptor with event counter or semaphore semantics, +designed for interprocess communication. +The returned file descriptor refers to a kernel object containing an +unsigned 64-bit integer counter, which is initialized with the value of the +.Fa initval +argument. +.Pp +The +.Fa flags +argument may contain the result of +.Em or Ns 'ing +the following values: +.Pp +.Bl -tag -width "EFD_SEMAPHORE" -compact +.It Dv EFD_CLOEXEC +set FD_CLOEXEC on the file descriptor +.It Dv EFD_NONBLOCK +do not block on read/write operations +.It Dv EFD_SEMAPHORE +use semaphore semantics +.El +.Pp +File operations have the following semantics: +.Bl -tag -width EFD_SEMAPHORE +.It Xr read 2 +If the counter is zero, the call blocks until the counter becomes non-zero, unless +.Dv EFD_NONBLOCK +was set, in which case it would fail with +.Dv EAGAIN +instead. +.Pp +If the counter is non-zero: +.Bl -bullet +.It +If +.Dv EFD_SEMAPHORE +is not set, the current value of the counter is returned, +and the value is reset to zero. +.It +If +.Dv EFD_SEMAPHORE +is set, the constant 1 is returned, and the value is decremented by 1. +.El +.Pp +The numeric value is encoded as 64-bit (8 bytes) in host byte order. +The +.Xr read 2 +call fails with +.Dv EINVAL +if there is less than 8 bytes available in the supplied buffer. +.It Xr write 2 +Adds the given value to the counter. +The maximum value that can be stored in the counter is the +maximum unsigned 64-bit integer value minus one (0xfffffffffffffffe). +.Pp +If the resulting value exceeds the maximum, the call would block +until the value is reduced by +.Xr read 2 , +unless +.Dv EFD_NONBLOCK +was set, in which case it would fail with +.Dv EAGAIN +instead. +.Pp +The numeric value is encoded as 64-bit (8 bytes) in host byte order. +The +.Xr write 2 +call fails with +.Dv EINVAL +if there is less than 8 bytes available in the supplied buffer, +or if the value 0xffffffffffffffff is given. +.It Xr poll 2 +When receiving notifications via +.Xr poll 2 / +.Xr ppoll 2 / +.Xr select 2 / +.Xr pselect 2 / +.Xr kqueue 2 , +the following semantics apply: +.Bl -bullet +.It +The file descriptor is readable when the counter is greater than zero. +.It +The file descriptor is writable when the counter is less than the maximum value. +.El +.El +.Pp +File descriptors created by +.Fn eventfd +are passable to other processes via +.Xr sendmsg 2 +and are preserved across +.Xr fork 2 ; +in both cases the descriptors refer to the same counter from both processes. +Unless +.Dv O_CLOEXEC +flag was specified, +the created file descriptor will remain open across +.Xr execve 2 +system calls; see +.Xr close 2 , +.Xr fcntl 2 +and +.Dv O_CLOEXEC +description. +.Pp +.Fn eventfd_read +and +.Fn eventfd_write +are thin wrappers around +.Xr read 2 +and +.Xr write 2 +system calls, +provided for compatibility with glibc. +.Sh RETURN VALUES +If successful, +.Fn eventfd +returns a non-negative integer, termed a file descriptor. +It returns \-1 on failure, and sets +.Va errno +to indicate the error. +.Pp +The +.Fn eventfd_read +and +.Fn eventfd_write +functions return 0 if the operation succeeded, -1 otherwise. +.Sh ERRORS +.Fn eventfd +may fail with: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa flags +argument given to +.Fn eventfd +has unknown bits set. +.It Bq Er EMFILE +The process has already reached its limit for open +file descriptors. +.It Bq Er ENFILE +The system file table is full. +.It Bq Er ENOMEM +No memory was available to create the kernel object. +.El +.Sh SEE ALSO +.Xr close 2 , +.Xr kqueue 2 , +.Xr poll 2 , +.Xr read 2 , +.Xr select 2 , +.Xr write 2 +.Sh STANDARDS +The +.Fn eventfd +system call is non-standard. +It is present in Linux. +.Sh HISTORY +The +.Fn eventfd +system call first appeared in +.Fx 13.0 . diff --git a/lib/libsys/execve.2 b/lib/libsys/execve.2 new file mode 100644 index 000000000000..dc85b9321e48 --- /dev/null +++ b/lib/libsys/execve.2 @@ -0,0 +1,382 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd July 02, 2025 +.Dt EXECVE 2 +.Os +.Sh NAME +.Nm execve , +.Nm fexecve +.Nd execute a file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn execve "const char *path" "char *const argv[]" "char *const envp[]" +.Ft int +.Fn fexecve "int fd" "char *const argv[]" "char *const envp[]" +.Sh DESCRIPTION +The +.Fn execve +system call +transforms the calling process into a new process. +The new process is constructed from an ordinary file, +whose name is pointed to by +.Fa path , +called the +.Em new process file . +The +.Fn fexecve +system call is equivalent to +.Fn execve +except that the file to be executed is determined by the file +descriptor +.Fa fd +instead of a +.Fa path . +This file is either an executable object file, +or a file of data for an interpreter. +An executable object file consists of an identifying header, +followed by pages of data representing the initial program (text) +and initialized data pages. +Additional pages may be specified +by the header to be initialized with zero data; see +.Xr elf 5 +and +.Xr a.out 5 . +.Pp +An interpreter file begins with a line of the form: +.Pp +.Bd -ragged -offset indent -compact +.Sy \&#! +.Em interpreter +.Bq Em arg +.Ed +.Pp +When an interpreter file is +.Sy execve Ap d , +the system actually +.Sy execve Ap s +the specified +.Em interpreter . +If the optional +.Em arg +is specified, it becomes the first argument to the +.Em interpreter , +and the name of the originally +.Sy execve Ap d +file becomes the second argument; +otherwise, the name of the originally +.Sy execve Ap d +file becomes the first argument. +The original arguments are shifted over to +become the subsequent arguments. +The zeroth argument is set to the specified +.Em interpreter . +.Pp +The argument +.Fa argv +is a pointer to a null-terminated array of +character pointers to null-terminated character strings. +These strings construct the argument list to be made available to the new +process. +At least one argument must be present in +the array; by custom, the first element should be +the name of the executed program (for example, the last component of +.Fa path ) . +.Pp +The argument +.Fa envp +is also a pointer to a null-terminated array of +character pointers to null-terminated strings. +A pointer to this array is normally stored in the global variable +.Va environ . +These strings pass information to the +new process that is not directly an argument to the command (see +.Xr environ 7 ) . +.Pp +File descriptors open in the calling process image remain open in +the new process image, except for those for which the close-on-exec +flag is set (see +.Xr close 2 +and +.Xr fcntl 2 ) . +Descriptors that remain open are unaffected by +.Fn execve , +except those with the close-on-fork flag +.Dv FD_CLOFORK +which is cleared from all file descriptors. +If any of the standard descriptors (0, 1, and/or 2) are closed at the +time +.Fn execve +is called, and the process will gain privilege as a result of set-id +semantics, those descriptors will be re-opened automatically. +No programs, whether privileged or not, should assume that these descriptors +will remain closed across a call to +.Fn execve . +.Pp +Signals set to be ignored in the calling process are set to be ignored in +the +new process. +Signals which are set to be caught in the calling process image +are set to default action in the new process image. +Blocked signals remain blocked regardless of changes to the signal action. +The signal stack is reset to be undefined (see +.Xr sigaction 2 +for more information). +.Pp +If the set-user-ID mode bit of the new process image file is set +(see +.Xr chmod 2 ) , +the effective user ID of the new process image is set to the owner ID +of the new process image file. +If the set-group-ID mode bit of the new process image file is set, +the effective group ID of the new process image is set to the group ID +of the new process image file. +(The effective group ID is the first element of the group list.) +The real user ID, real group ID and +other group IDs of the new process image remain the same as the calling +process image. +After any set-user-ID and set-group-ID processing, +the effective user ID is recorded as the saved set-user-ID, +and the effective group ID is recorded as the saved set-group-ID. +These values may be used in changing the effective IDs later (see +.Xr setuid 2 ) . +.Pp +The set-ID bits are not honored if the respective file system has the +.Cm nosuid +option enabled or if the new process file is an interpreter file. +Syscall +tracing is disabled if effective IDs are changed. +.Pp +The new process also inherits the following attributes from +the calling process: +.Pp +.Bl -column parent_process_ID -offset indent -compact +.It process ID Ta see Xr getpid 2 +.It parent process ID Ta see Xr getppid 2 +.It process group ID Ta see Xr getpgrp 2 +.It access groups Ta see Xr getgroups 2 +.It working directory Ta see Xr chdir 2 +.It root directory Ta see Xr chroot 2 +.It control terminal Ta see Xr termios 4 +.It resource usages Ta see Xr getrusage 2 +.It interval timers Ta see Xr getitimer 2 +.It resource limits Ta see Xr getrlimit 2 +.It file mode mask Ta see Xr umask 2 +.It signal mask Ta see Xr sigaction 2 , +.Xr sigprocmask 2 +.El +.Pp +When a program is executed as a result of an +.Fn execve +system call, it is entered as follows: +.Bd -literal -offset indent +main(argc, argv, envp) +int argc; +char **argv, **envp; +.Ed +.Pp +where +.Fa argc +is the number of elements in +.Fa argv +(the ``arg count'') +and +.Fa argv +points to the array of character pointers +to the arguments themselves. +.Pp +The +.Fn fexecve +ignores the file offset of +.Fa fd . +Since execute permission is checked by +.Fn fexecve , +the file descriptor +.Fa fd +need not have been opened with the +.Dv O_EXEC +flag. +However, if the file to be executed denies read permission for the process +preparing to do the exec, the only way to provide the +.Fa fd +to +.Fn fexecve +is to use the +.Dv O_EXEC +flag when opening +.Fa fd . +Note that the file to be executed can not be open for writing. +.Sh RETURN VALUES +As the +.Fn execve +system call overlays the current process image +with a new process image the successful call +has no process to return to. +If +.Fn execve +does return to the calling process an error has occurred; the +return value will be -1 and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn execve +system call +will fail and return to the calling process if: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOEXEC +When invoking an interpreted script, the length of the first line, +inclusive of the +.Sy \&#! +prefix and terminating newline, exceeds +.Dv MAXSHELLCMDLEN +characters. +.It Bq Er ENOENT +The new process file does not exist. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er EACCES +The new process file is not an ordinary file. +.It Bq Er EACCES +The new process file mode denies execute permission. +.It Bq Er EINVAL +.Fa argv +did not contain at least one element. +.It Bq Er ENOEXEC +The new process file has the appropriate access +permission, but has an invalid magic number in its header. +.It Bq Er ETXTBSY +The new process file is a pure procedure (shared text) +file that is currently open for writing by some process. +.It Bq Er ENOMEM +The new process requires more virtual memory than +is allowed by the imposed maximum +.Pq Xr getrlimit 2 . +.It Bq Er E2BIG +The number of bytes in the new process' argument list +is larger than the system-imposed limit. +This limit is specified by the +.Xr sysctl 3 +MIB variable +.Dv KERN_ARGMAX . +.It Bq Er EFAULT +The new process file is not as long as indicated by +the size values in its header. +.It Bq Er EFAULT +The +.Fa path , +.Fa argv , +or +.Fa envp +arguments +point +to an illegal address. +.It Bq Er EIO +An I/O error occurred while reading from the file system. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.El +.Pp +In addition, the +.Fn fexecve +will fail and return to the calling process if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid file descriptor open for executing. +.El +.Sh SEE ALSO +.Xr ktrace 1 , +.Xr _exit 2 , +.Xr fork 2 , +.Xr open 2 , +.Xr execl 3 , +.Xr exit 3 , +.Xr sysctl 3 , +.Xr fdescfs 4 , +.Xr a.out 5 , +.Xr elf 5 , +.Xr environ 7 , +.Xr mount 8 +.Sh STANDARDS +The +.Fn execve +system call conforms to +.St -p1003.1-2001 , +with the exception of reopening descriptors 0, 1, and/or 2 in certain +circumstances. +A future update of the Standard is expected to require this behavior, +and it may become the default for non-privileged processes as well. +.\" NB: update this caveat when TC1 is blessed. +The support for executing interpreted programs is an extension. +The +.Fn fexecve +system call conforms to The Open Group Extended API Set 2 specification. +.Sh HISTORY +The +.Fn execve +system call appeared in +.At v7 . +The +.Fn fexecve +system call appeared in +.Fx 8.0 . +.Sh CAVEATS +If a program is +.Em setuid +to a non-super-user, but is executed when +the real +.Em uid +is ``root'', then the program has some of the powers +of a super-user as well. +.Pp +When executing an interpreted program through +.Fn fexecve , +kernel supplies +.Pa /dev/fd/n +as a second argument to the interpreter, +where +.Ar n +is the file descriptor passed in the +.Fa fd +argument to +.Fn fexecve . +For this construction to work correctly, the +.Xr fdescfs 4 +filesystem shall be mounted on +.Pa /dev/fd . diff --git a/lib/libsys/extattr_get_file.2 b/lib/libsys/extattr_get_file.2 new file mode 100644 index 000000000000..f66c64160d55 --- /dev/null +++ b/lib/libsys/extattr_get_file.2 @@ -0,0 +1,290 @@ +.\" +.\" Copyright (c) 2001 Dima Dorfman <dima@unixfreak.org> +.\" Copyright (c) 2003 Robert Watson <rwatson@FreeBSD.org> +.\" All rights reserved. +.\" +.\" 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. +.\" +.Dd October 11, 2021 +.Dt EXTATTR 2 +.Os +.Sh NAME +.Nm extattr_delete_fd , +.Nm extattr_delete_file , +.Nm extattr_delete_link , +.Nm extattr_get_fd , +.Nm extattr_get_file , +.Nm extattr_get_link , +.Nm extattr_list_fd , +.Nm extattr_list_file , +.Nm extattr_list_link , +.Nm extattr_set_fd , +.Nm extattr_set_file , +.Nm extattr_set_link +.Nd system calls to manipulate VFS extended attributes +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/extattr.h +.Ft int +.Fn extattr_delete_fd "int fd" "int attrnamespace" "const char *attrname" +.Ft int +.Fn extattr_delete_file "const char *path" "int attrnamespace" "const char *attrname" +.Ft int +.Fn extattr_delete_link "const char *path" "int attrnamespace" "const char *attrname" +.Ft ssize_t +.Fn extattr_get_fd "int fd" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes" +.Ft ssize_t +.Fn extattr_get_file "const char *path" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes" +.Ft ssize_t +.Fn extattr_get_link "const char *path" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes" +.Ft ssize_t +.Fn extattr_list_fd "int fd" "int attrnamespace" "void *data" "size_t nbytes" +.Ft ssize_t +.Fn extattr_list_file "const char *path" "int attrnamespace" "void *data" "size_t nbytes" +.Ft ssize_t +.Fn extattr_list_link "const char *path" "int attrnamespace" "void *data" "size_t nbytes" +.Ft ssize_t +.Fn extattr_set_fd "int fd" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes" +.Ft ssize_t +.Fn extattr_set_file "const char *path" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes" +.Ft ssize_t +.Fn extattr_set_link "const char *path" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes" +.Sh DESCRIPTION +Named extended attributes are meta-data associated with vnodes +representing files and directories. +They exist as +.Qq Li name=value +pairs within a set of namespaces. +.Pp +The +.Fn extattr_get_file +system call retrieves the value of the specified extended attribute into +a buffer pointed to by +.Fa data +of size +.Fa nbytes . +The +.Fn extattr_set_file +system call sets the value of the specified extended attribute to the data +described by +.Fa data . +The +.Fn extattr_delete_file +system call deletes the extended attribute specified. +The +.Fn extattr_list_file +returns a list of attributes present in the requested namespace. +Each list entry consists of a single byte containing the length +of the attribute name, followed by the attribute name. +The attribute name is not terminated by ASCII 0 (nul). +The +.Fn extattr_get_file +and +.Fn extattr_list_file +calls consume the +.Fa data +and +.Fa nbytes +arguments in the style of +.Xr read 2 ; +.Fn extattr_set_file +consumes these arguments in the style of +.Xr write 2 . +.Pp +If +.Fa data +is +.Dv NULL +in a call to +.Fn extattr_get_file +and +.Fn extattr_list_file +then the size of defined extended attribute data will be returned, rather +than the quantity read, permitting applications to test the size of the +data without performing a read. +The +.Fn extattr_delete_link , +.Fn extattr_get_link , +and +.Fn extattr_set_link +system calls behave in the same way as their _file counterparts, except that +they do not follow symlinks. +.Pp +The +.Fn extattr_get_fd , +.Fn extattr_delete_fd , +.Fn extattr_list_fd , +and +.Fn extattr_set_fd +calls are identical to their +.Qq Li _file +counterparts except for the first argument. +The +.Qq Li _fd +functions take a file descriptor, while the +.Qq Li _file +functions take a path. +Both arguments describe a file associated with the extended attribute +that should be manipulated. +The +.Qq Li _fd +functions can be used with file descriptors opened with the +.Dv O_PATH +flag. +.Pp +The following arguments are common to all the system calls described here: +.Bl -tag -width attrnamespace +.It Fa attrnamespace +the namespace in which the extended attribute resides; see +.Xr extattr 9 +.It Fa attrname +the name of the extended attribute +.El +.Pp +Named extended attribute semantics vary by file system implementing the call. +Not all operations may be supported for a particular attribute. +Additionally, the format of the data in +.Fa data +is attribute-specific. +.Pp +For more information on named extended attributes, please see +.Xr extattr 9 . +.Sh RETURN VALUES +If successful, the +.Fn extattr_get_fd , +.Fn extattr_get_file , +.Fn extattr_get_link , +.Fn extattr_list_fd , +.Fn extattr_list_file , +.Fn extattr_list_link , +.Fn extattr_set_fd , +.Fn extattr_set_file , +and +.Fn extattr_set_link +calls return the number of bytes +that were read or written from the +.Fa data , +respectively. +If +.Fa data +was +.Dv NULL , +then +.Fn extattr_get_fd , +.Fn extattr_get_file , +.Fn extattr_get_link , +.Fn extattr_list_fd , +.Fn extattr_list_file , +and +.Fn extattr_list_link +return the number of bytes available to read. +If any of the calls are unsuccessful, the value \-1 is returned +and the global variable +.Va errno +is set to indicate the error. +.Pp +.Rv -std extattr_delete_file +.Sh ERRORS +The following errors may be returned by the system calls themselves. +Additionally, the file system implementing the call may return any +other errors it desires. +.Bl -tag -width Er +.It Bq Er EFAULT +The +.Fa attrnamespace +and +.Fa attrname +arguments, +or the memory range defined by +.Fa data +and +.Fa nbytes +point outside the process's allocated address space. +.It Bq Er ENAMETOOLONG +The attribute name was longer than +.Dv EXTATTR_MAXNAMELEN . +.El +.Pp +The +.Fn extattr_get_fd , +.Fn extattr_set_fd , +.Fn extattr_delete_fd , +and +.Fn extattr_list_fd +system calls may also fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The file descriptor referenced by +.Fa fd +was invalid. +.El +.Pp +Additionally, the +.Fn extattr_get_file , +.Fn extattr_set_file , +and +.Fn extattr_delete_file +calls may also fail due to the following errors: +.Bl -tag -width Er +.It Bq Er ENOATTR +The requested attribute was not defined for this file. +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +A component of the path name that must exist does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.\" XXX are any missing? +.El +.Sh SEE ALSO +.Xr extattr 3 , +.Xr getextattr 8 , +.Xr setextattr 8 , +.Xr extattr 9 , +.Xr VOP_GETEXTATTR 9 , +.Xr VOP_SETEXTATTR 9 +.Sh HISTORY +Extended attribute support was developed as part of the +.Tn TrustedBSD +Project, and introduced in +.Fx 5.0 . +It was developed to support security extensions requiring additional labels +to be associated with each file or directory. +.Sh CAVEATS +This interface is under active development, and as such is subject to +change as applications are adapted to use it. +Developers are discouraged from relying on its stability. +.Sh BUGS +In earlier versions of this API, passing an empty string for the +attribute name to +.Fn extattr_get_fd , +.Fn extattr_get_file , +or +.Fn extattr_get_link +would return the list of attributes defined for the target object. +This interface has been deprecated in preference to using the explicit +list API, and should not be used. diff --git a/lib/libsys/fcntl.2 b/lib/libsys/fcntl.2 new file mode 100644 index 000000000000..d67c38cfbc6c --- /dev/null +++ b/lib/libsys/fcntl.2 @@ -0,0 +1,848 @@ +.\" Copyright (c) 1983, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd June 24, 2025 +.Dt FCNTL 2 +.Os +.Sh NAME +.Nm fcntl +.Nd file control +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In fcntl.h +.Ft int +.Fn fcntl "int fd" "int cmd" "..." +.Sh DESCRIPTION +The +.Fn fcntl +system call provides for control over descriptors. +The argument +.Fa fd +is a descriptor to be operated on by +.Fa cmd +as described below. +Depending on the value of +.Fa cmd , +.Fn fcntl +can take an additional third argument +.Fa arg . +Unless otherwise noted below for a specific operation, +.Fa arg +has type +.Vt int . +.Bl -tag -width F_DUP2FD_CLOEXEC +.It Dv F_DUPFD +Return a new descriptor as follows: +.Pp +.Bl -bullet -compact -offset 4n +.It +Lowest numbered available descriptor greater than or equal to +.Fa arg . +.It +Same object references as the original descriptor. +.It +New descriptor shares the same file offset if the object +was a file. +.It +Same access mode (read, write or read/write). +.It +Same file status flags (i.e., both file descriptors +share the same file status flags). +.It +The close-on-exec flag +.Dv FD_CLOEXEC +associated with the new file descriptor is cleared, so the file descriptor is +to remain open across +.Xr execve 2 +system calls. +.It +The fork-on-exec flag +.Dv FD_CLOFORK +associated with the new file descriptor is cleared, so the file descriptor is +to remain open across +.Xr fork 2 +system calls. +.It +The +.Dv FD_RESOLVE_BENEATH +flag, described below, will be set if it was set on the original +descriptor. +.El +.It Dv F_DUPFD_CLOEXEC +Like +.Dv F_DUPFD , +but the +.Dv FD_CLOEXEC +flag associated with the new file descriptor is set, so the file descriptor +is closed when +.Xr execve 2 +system call executes. +.It Dv F_DUPFD_CLOFORK +Like +.Dv F_DUPFD , +but the +.Dv FD_CLOFORK +flag associated with the new file descriptor is set, so the file descriptor +is closed when +.Xr fork 2 +system call executes. +.It Dv F_DUP2FD +It is functionally equivalent to +.Bd -literal -offset indent +dup2(fd, arg) +.Ed +.It Dv F_DUP2FD_CLOEXEC +Like +.Dv F_DUP2FD , +but the +.Dv FD_CLOEXEC +flag associated with the new file descriptor is set. +.Pp +The +.Dv F_DUP2FD +and +.Dv F_DUP2FD_CLOEXEC +constants are not portable, so they should not be used if +portability is needed. +Use +.Fn dup2 +instead of +.Dv F_DUP2FD . +.It Dv F_DUP3FD +Used to implement the +.Fn dup3 +call. +Do not use it. +.It Dv F_GETFD +Get the flags associated with the file descriptor +.Fa fd . +The following flags are defined: +.Bl -tag -width FD_RESOLVE_BENEATH +.It Dv FD_CLOEXEC +The file will be closed upon execution of +.Fn exec +.Fa ( arg +is ignored). +Otherwise, the file descriptor will remain open. +.It Dv FD_CLOFORK +The file will be closed upon execution of the +.Fn fork +family of system calls. +.It Dv FD_RESOLVE_BENEATH +All path name lookups relative to that file descriptor +will behave as if the lookup had +.Dv O_RESOLVE_BENEATH +or +.Dv AT_RESOLVE_BENEATH +semantics. +It is not permitted to call +.Xr fchdir 2 +or +.Xr fchroot 2 +on such a file descriptor. +The +.Dv FD_RESOLVE_BENEATH +flag is sticky, meaning that it is preserved by +.Xr dup 2 +and similar operations, and opening a directory with +.Xr openat 2 +where the directory descriptor has the flag set causes the new directory +descriptor to also have the flag set. +.El +.It Dv F_SETFD +Set flags associated with +.Fa fd . +The available flags are +.Dv FD_CLOEXEC , +.Dv FD_CLOFORK +and +.Dv FD_RESOLVE_BENEATH . +The +.Dv FD_RESOLVE_BENEATH +flag cannot be cleared once set. +.It Dv F_GETFL +Get descriptor status flags, as described below +.Fa ( arg +is ignored). +.It Dv F_SETFL +Set descriptor status flags to +.Fa arg . +.It Dv F_GETOWN +Get the process ID or process group +currently receiving +.Dv SIGIO +and +.Dv SIGURG +signals; process groups are returned +as negative values +.Fa ( arg +is ignored). +.It Dv F_SETOWN +Set the process or process group +to receive +.Dv SIGIO +and +.Dv SIGURG +signals; +process groups are specified by supplying +.Fa arg +as negative, otherwise +.Fa arg +is interpreted as a process ID. +.It Dv F_READAHEAD +Set or clear the read ahead amount for sequential access to the third +argument, +.Fa arg , +which is rounded up to the nearest block size. +A zero value in +.Fa arg +turns off read ahead, a negative value restores the system default. +.It Dv F_RDAHEAD +Equivalent to Darwin counterpart which sets read ahead amount of 128KB +when the third argument, +.Fa arg +is non-zero. +A zero value in +.Fa arg +turns off read ahead. +.It Dv F_ADD_SEALS +Add seals to the file as described below, if the underlying filesystem supports +seals. +.It Dv F_GET_SEALS +Get seals associated with the file, if the underlying filesystem supports seals. +.It Dv F_ISUNIONSTACK +Check if the vnode is part of a union stack (either the "union" flag from +.Xr mount 2 +or unionfs). +This is a hack not intended to be used outside of libc. +.It Dv F_KINFO +Fills a +.Vt struct kinfo_file +for the file referenced by the specified file descriptor. +The +.Fa arg +argument should point to the storage for +.Vt struct kinfo_file . +The +.Va kf_structsize +member of the passed structure must be initialized with the sizeof of +.Vt struct kinfo_file , +to allow for the interface versioning and evolution. +.El +.Pp +The flags for the +.Dv F_GETFL +and +.Dv F_SETFL +commands are as follows: +.Bl -tag -width O_NONBLOCKX +.It Dv O_NONBLOCK +Non-blocking I/O; if no data is available to a +.Xr read 2 +system call, or if a +.Xr write 2 +operation would block, +the read or write call returns -1 with the error +.Er EAGAIN . +.It Dv O_APPEND +Force each write to append at the end of file; +corresponds to the +.Dv O_APPEND +flag of +.Xr open 2 . +.It Dv O_DIRECT +Minimize or eliminate the cache effects of reading and writing. +The system +will attempt to avoid caching the data you read or write. +If it cannot +avoid caching the data, it will minimize the impact the data has on the cache. +Use of this flag can drastically reduce performance if not used with care. +.It Dv O_ASYNC +Enable the +.Dv SIGIO +signal to be sent to the process group +when I/O is possible, e.g., +upon availability of data to be read. +.It Dv O_SYNC +Enable synchronous writes. +Corresponds to the +.Dv O_SYNC +flag of +.Xr open 2 . +.Dv O_FSYNC +is an historical synonym for +.Dv O_SYNC . +.It Dv O_DSYNC +Enable synchronous data writes. +Corresponds to the +.Dv O_DSYNC +flag of +.Xr open 2 . +.El +.Pp +The seals that may be applied with +.Dv F_ADD_SEALS +are as follows: +.Bl -tag -width F_SEAL_SHRINK +.It Dv F_SEAL_SEAL +Prevent any further seals from being applied to the file. +.It Dv F_SEAL_SHRINK +Prevent the file from being shrunk with +.Xr ftruncate 2 . +.It Dv F_SEAL_GROW +Prevent the file from being enlarged with +.Xr ftruncate 2 . +.It Dv F_SEAL_WRITE +Prevent any further +.Xr write 2 +calls to the file. +Any writes in progress will finish before +.Fn fcntl +returns. +If any writeable mappings exist, F_ADD_SEALS will fail and return +.Dv EBUSY . +.El +.Pp +Seals are on a per-inode basis and require support by the underlying filesystem. +If the underlying filesystem does not support seals, +.Dv F_ADD_SEALS +and +.Dv F_GET_SEALS +will fail and return +.Dv EINVAL . +.Pp +Several operations are available for doing advisory file locking; +they all operate on the following structure: +.Bd -literal +struct flock { + off_t l_start; /* starting offset */ + off_t l_len; /* len = 0 means until end of file */ + pid_t l_pid; /* lock owner */ + short l_type; /* lock type: read/write, etc. */ + short l_whence; /* type of l_start */ + int l_sysid; /* remote system id or zero for local */ +}; +.Ed +These advisory file locking operations take a pointer to +.Vt struct flock +as the third argument +.Fa arg . +The commands available for advisory record locking are as follows: +.Bl -tag -width F_SETLKWX +.It Dv F_GETLK +Get the first lock that blocks the lock description pointed to by the +third argument, +.Fa arg , +taken as a pointer to a +.Fa "struct flock" +(see above). +The information retrieved overwrites the information passed to +.Fn fcntl +in the +.Fa flock +structure. +If no lock is found that would prevent this lock from being created, +the structure is left unchanged by this system call except for the +lock type which is set to +.Dv F_UNLCK . +.It Dv F_SETLK +Set or clear a file segment lock according to the lock description +pointed to by the third argument, +.Fa arg , +taken as a pointer to a +.Fa "struct flock" +(see above). +.Dv F_SETLK +is used to establish shared (or read) locks +.Pq Dv F_RDLCK +or exclusive (or write) locks, +.Pq Dv F_WRLCK , +as well as remove either type of lock +.Pq Dv F_UNLCK . +If a shared or exclusive lock cannot be set, +.Fn fcntl +returns immediately with +.Er EAGAIN . +.It Dv F_SETLKW +This command is the same as +.Dv F_SETLK +except that if a shared or exclusive lock is blocked by other locks, +the process waits until the request can be satisfied. +If a signal that is to be caught is received while +.Fn fcntl +is waiting for a region, the +.Fn fcntl +will be interrupted if the signal handler has not specified the +.Dv SA_RESTART +(see +.Xr sigaction 2 ) . +.El +.Pp +When a shared lock has been set on a segment of a file, +other processes can set shared locks on that segment +or a portion of it. +A shared lock prevents any other process from setting an exclusive +lock on any portion of the protected area. +A request for a shared lock fails if the file descriptor was not +opened with read access. +.Pp +An exclusive lock prevents any other process from setting a shared lock or +an exclusive lock on any portion of the protected area. +A request for an exclusive lock fails if the file was not +opened with write access. +.Pp +The value of +.Fa l_whence +is +.Dv SEEK_SET , +.Dv SEEK_CUR , +or +.Dv SEEK_END +to indicate that the relative offset, +.Fa l_start +bytes, will be measured from the start of the file, +current position, or end of the file, respectively. +The value of +.Fa l_len +is the number of consecutive bytes to be locked. +If +.Fa l_len +is negative, +.Fa l_start +means end edge of the region. +The +.Fa l_pid +and +.Fa l_sysid +fields are only used with +.Dv F_GETLK +to return the process ID of the process holding a blocking lock and +the system ID of the system that owns that process. +Locks created by the local system will have a system ID of zero. +After a successful +.Dv F_GETLK +request, the value of +.Fa l_whence +is +.Dv SEEK_SET . +.Pp +Locks may start and extend beyond the current end of a file, +but may not start or extend before the beginning of the file. +A lock is set to extend to the largest possible value of the +file offset for that file if +.Fa l_len +is set to zero. +If +.Fa l_whence +and +.Fa l_start +point to the beginning of the file, and +.Fa l_len +is zero, the entire file is locked. +If an application wishes only to do entire file locking, the +.Xr flock 2 +system call is much more efficient. +.Pp +There is at most one type of lock set for each byte in the file. +Before a successful return from an +.Dv F_SETLK +or an +.Dv F_SETLKW +request when the calling process has previously existing locks +on bytes in the region specified by the request, +the previous lock type for each byte in the specified +region is replaced by the new lock type. +As specified above under the descriptions +of shared locks and exclusive locks, an +.Dv F_SETLK +or an +.Dv F_SETLKW +request fails or blocks respectively when another process has existing +locks on bytes in the specified region and the type of any of those +locks conflicts with the type specified in the request. +.Pp +The queuing for +.Dv F_SETLKW +requests on local files is fair; +that is, while the thread is blocked, +subsequent requests conflicting with its requests will not be granted, +even if these requests do not conflict with existing locks. +.Pp +This interface follows the completely stupid semantics of System V and +.St -p1003.1-88 +that require that all locks associated with a file for a given process are +removed when +.Em any +file descriptor for that file is closed by that process. +This semantic means that applications must be aware of any files that +a subroutine library may access. +For example if an application for updating the password file locks the +password file database while making the update, and then calls +.Xr getpwnam 3 +to retrieve a record, +the lock will be lost because +.Xr getpwnam 3 +opens, reads, and closes the password database. +The database close will release all locks that the process has +associated with the database, even if the library routine never +requested a lock on the database. +Another minor semantic problem with this interface is that +locks are not inherited by a child process created using the +.Xr fork 2 +system call. +The +.Xr flock 2 +interface has much more rational last close semantics and +allows locks to be inherited by child processes. +The +.Xr flock 2 +system call is recommended for applications that want to ensure the integrity +of their locks when using library routines or wish to pass locks +to their children. +.Pp +The +.Fn fcntl , +.Xr flock 2 , +and +.Xr lockf 3 +locks are compatible. +Processes using different locking interfaces can cooperate +over the same file safely. +However, only one of such interfaces should be used within +the same process. +If a file is locked by a process through +.Xr flock 2 , +any record within the file will be seen as locked +from the viewpoint of another process using +.Fn fcntl +or +.Xr lockf 3 , +and vice versa. +Note that +.Fn fcntl F_GETLK +returns \-1 in +.Fa l_pid +if the process holding a blocking lock previously locked the +file descriptor by +.Xr flock 2 . +.Pp +All locks associated with a file for a given process are +removed when the process terminates. +.Pp +All locks obtained before a call to +.Xr execve 2 +remain in effect until the new program releases them. +If the new program does not know about the locks, they will not be +released until the program exits. +.Pp +A potential for deadlock occurs if a process controlling a locked region +is put to sleep by attempting to lock the locked region of another process. +This implementation detects that sleeping until a locked region is unlocked +would cause a deadlock and fails with an +.Er EDEADLK +error. +.Sh RETURN VALUES +Upon successful completion, the value returned depends on +.Fa cmd +as follows: +.Bl -tag -width F_GETOWNX -offset indent +.It Dv F_DUPFD +A new file descriptor. +.It Dv F_DUP2FD +A file descriptor equal to +.Fa arg . +.It Dv F_GETFD +Value of flags. +.It Dv F_GETFL +Value of flags. +.It Dv F_GETOWN +Value of file descriptor owner. +.It other +Value other than -1. +.El +.Pp +Otherwise, a value of -1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn fcntl +system call will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The argument +.Fa cmd +is +.Dv F_SETLK , +the type of lock +.Pq Fa l_type +is a shared lock +.Pq Dv F_RDLCK +or exclusive lock +.Pq Dv F_WRLCK , +and the segment of a file to be locked is already +exclusive-locked by another process; +or the type is an exclusive lock and some portion of the +segment of a file to be locked is already shared-locked or +exclusive-locked by another process. +.It Bq Er EBADF +The +.Fa fd +argument +is not a valid open file descriptor. +.Pp +The argument +.Fa cmd +is +.Dv F_DUP2FD , +and +.Fa arg +is not a valid file descriptor. +.Pp +The argument +.Fa cmd +is +.Dv F_SETLK +or +.Dv F_SETLKW , +the type of lock +.Pq Fa l_type +is a shared lock +.Pq Dv F_RDLCK , +and +.Fa fd +is not a valid file descriptor open for reading. +.Pp +The argument +.Fa cmd +is +.Dv F_SETLK +or +.Dv F_SETLKW , +the type of lock +.Pq Fa l_type +is an exclusive lock +.Pq Dv F_WRLCK , +and +.Fa fd +is not a valid file descriptor open for writing. +.It Bq Er EBUSY +The argument +.Fa cmd +is +.Dv F_ADD_SEALS , +attempting to set +.Dv F_SEAL_WRITE , +and writeable mappings of the file exist. +.It Bq Er EDEADLK +The argument +.Fa cmd +is +.Dv F_SETLKW , +and a deadlock condition was detected. +.It Bq Er EINTR +The argument +.Fa cmd +is +.Dv F_SETLKW , +and the system call was interrupted by a signal. +.It Bq Er EINVAL +The +.Fa cmd +argument +is +.Dv F_DUPFD +and +.Fa arg +is negative or greater than the maximum allowable number +(see +.Xr getdtablesize 2 ) . +.Pp +The argument +.Fa cmd +is +.Dv F_GETLK , +.Dv F_SETLK +or +.Dv F_SETLKW +and the data to which +.Fa arg +points is not valid. +.Pp +The argument +.Fa cmd +is +.Dv F_ADD_SEALS +or +.Dv F_GET_SEALS , +and the underlying filesystem does not support sealing. +.Pp +The argument +.Fa cmd +is invalid. +.It Bq Er EMFILE +The argument +.Fa cmd +is +.Dv F_DUPFD +and the maximum number of file descriptors permitted for the +process are already in use, +or no file descriptors greater than or equal to +.Fa arg +are available. +.It Bq Er ENOTTY +The +.Fa fd +argument is not a valid file descriptor for the requested operation. +This may be the case if +.Fa fd +is a device node, or a descriptor returned by +.Xr kqueue 2 . +.It Bq Er ENOLCK +The argument +.Fa cmd +is +.Dv F_SETLK +or +.Dv F_SETLKW , +and satisfying the lock or unlock request would result in the +number of locked regions in the system exceeding a system-imposed limit. +.It Bq Er EOPNOTSUPP +The argument +.Fa cmd +is +.Dv F_GETLK , +.Dv F_SETLK +or +.Dv F_SETLKW +and +.Fa fd +refers to a file for which locking is not supported. +.It Bq Er EOVERFLOW +The argument +.Fa cmd +is +.Dv F_GETLK , +.Dv F_SETLK +or +.Dv F_SETLKW +and an +.Fa off_t +calculation overflowed. +.It Bq Er EPERM +The +.Fa cmd +argument +is +.Dv F_SETOWN +and +the process ID or process group given as an argument is in a +different session than the caller. +.Pp +The +.Fa cmd +argument +is +.Dv F_ADD_SEALS +and the +.Dv F_SEAL_SEAL +seal has already been set. +.It Bq Er ESRCH +The +.Fa cmd +argument +is +.Dv F_SETOWN +and +the process ID given as argument is not in use. +.El +.Pp +In addition, if +.Fa fd +refers to a descriptor open on a terminal device (as opposed to a +descriptor open on a socket), a +.Fa cmd +of +.Dv F_SETOWN +can fail for the same reasons as in +.Xr tcsetpgrp 3 , +and a +.Fa cmd +of +.Dv F_GETOWN +for the reasons as stated in +.Xr tcgetpgrp 3 . +.Sh SEE ALSO +.Xr close 2 , +.Xr dup2 2 , +.Xr execve 2 , +.Xr flock 2 , +.Xr getdtablesize 2 , +.Xr open 2 , +.Xr sigaction 2 , +.Xr lockf 3 , +.Xr tcgetpgrp 3 , +.Xr tcsetpgrp 3 +.Sh STANDARDS +The +.Dv F_DUP2FD +and +.Dv F_DUP3FD +constants are not portable. +They are provided for compatibility with AIX and Solaris. +.Pp +Per +.St -susv4 , +a call with +.Dv F_SETLKW +should fail with +.Bq Er EINTR +after any caught signal +and should continue waiting during thread suspension such as a stop signal. +However, in this implementation a call with +.Dv F_SETLKW +is restarted after catching a signal with a +.Dv SA_RESTART +handler or a thread suspension such as a stop signal. +.Sh HISTORY +The +.Fn fcntl +system call appeared in +.Bx 4.2 . +.Pp +The +.Dv F_DUP2FD +constant first appeared in +.Fx 7.1 . +.Pp +The +.Dv F_DUPFD_CLOFORK +and +.Dv F_DUP3FD +flags appeared in +.Fx 15.0 . diff --git a/lib/libsys/ffclock.2 b/lib/libsys/ffclock.2 new file mode 100644 index 000000000000..2e34c5cd8e9d --- /dev/null +++ b/lib/libsys/ffclock.2 @@ -0,0 +1,175 @@ +.\" Copyright (c) 2011 The University of Melbourne +.\" All rights reserved. +.\" +.\" This documentation was written by Julien Ridoux at the University of +.\" Melbourne under sponsorship from the FreeBSD Foundation. +.\" +.\" 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. +.\" +.Dd November 21, 2011 +.Dt FFCLOCK 2 +.Os +.Sh NAME +.Nm ffclock_getcounter , +.Nm ffclock_getestimate , +.Nm ffclock_setestimate +.Nd Retrieve feed-forward counter, get and set feed-forward clock estimates +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/timeffc.h +.Ft int +.Fn ffclock_getcounter "ffcounter *ffcount" +.Ft int +.Fn ffclock_getestimate "struct ffclock_estimate *cest" +.Ft int +.Fn ffclock_setestimate "struct ffclock_estimate *cest" +.Sh DESCRIPTION +The ffclock is an alternative method to synchronise the system clock. +The ffclock implements a feed-forward paradigm and decouples the timestamping +and timekeeping kernel functions. +This ensures that past clock errors do not affect current timekeeping, an +approach radically different from the feedback alternative implemented by the +ntpd daemon when adjusting the system clock. +The feed-forward approach has demonstrated better performance and higher +robustness than a feedback approach when synchronising over the network. +.Pp +In the feed-forward context, a +.Em timestamp +is a cumulative value of the ticks of the timecounter, which can be converted +into seconds by using the feed-forward +.Em clock estimates . +.Pp +The +.Fn ffclock_getcounter +system call allows the calling process to retrieve the current value of the +feed-forward counter maintained by the kernel. +.Pp +The +.Fn ffclock_getestimate +and +.Fn ffclock_setestimate +system calls allow the caller to get and set the kernel's feed-forward clock +parameter estimates respectively. +The +.Fn ffclock_setestimate +system call should be invoked by a single instance of a feed-forward +synchronisation daemon. +The +.Fn ffclock_getestimate +system call can be called by any process to retrieve the feed-forward clock +estimates. +.Pp +The feed-forward approach does not require that the clock estimates be retrieved +every time a timestamp is to be converted into seconds. +The number of system calls can therefore be greatly reduced if the calling +process retrieves the clock estimates from the clock synchronisation daemon +instead. +The +.Fn ffclock_getestimate +must be used when the feed-forward synchronisation daemon is not running +.Po see +.Sx USAGE +below +.Pc . +.Pp +The clock parameter estimates structure pointed to by +.Fa cest +is defined in +.In sys/timeffc.h +as: +.Bd -literal +struct ffclock_estimate { + struct bintime update_time; /* Time of last estimates update. */ + ffcounter update_ffcount; /* Counter value at last update. */ + ffcounter leapsec_next; /* Counter value of next leap second. */ + uint64_t period; /* Estimate of counter period. */ + uint32_t errb_abs; /* Bound on absolute clock error [ns]. */ + uint32_t errb_rate; /* Bound on counter rate error [ps/s]. */ + uint32_t status; /* Clock status. */ + int16_t leapsec_total; /* All leap seconds seen so far. */ + int8_t leapsec; /* Next leap second (in {-1,0,1}). */ +}; +.Ed +.Pp +Only the super-user may set the feed-forward clock estimates. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The following error codes may be set in +.Va errno : +.Bl -tag -width Er +.It Bq Er EFAULT +The +.Fa ffcount +or +.Fa cest +pointer referenced invalid memory. +.It Bq Er EPERM +A user other than the super-user attempted to set the feed-forward clock +parameter estimates. +.El +.Sh USAGE +The feed-forward paradigm enables the definition of specialised clock functions. +.Pp +In its simplest form, +.Fn ffclock_getcounter +can be used to establish strict order between events or to measure small time +intervals very accurately with a minimum performance cost. +.Pp +Different methods exist to access absolute time +.Po or +.Qq wall-clock time +.Pc tracked by the ffclock. +The simplest method uses the ffclock sysctl interface +.Va kern.ffclock +to make the system clock return the ffclock time. +The +.Xr clock_gettime 2 +system call can then be used to retrieve the current time seen by the +feed-forward clock. +Note that this setting affects the entire system and that a feed-forward +synchronisation daemon should be running. +.Pp +A less automated method consists of retrieving the feed-forward counter +timestamp from the kernel and using the feed-forward clock parameter estimates +to convert the timestamp into seconds. +The feed-forward clock parameter estimates can be retrieved from the kernel or +from the synchronisation daemon directly (preferred). +This method allows converting timestamps using different clock models as needed +by the application, while collecting meaningful upper bounds on current clock +error. +.Sh SEE ALSO +.Xr date 1 , +.Xr adjtime 2 , +.Xr clock_gettime 2 , +.Xr ctime 3 +.Sh HISTORY +Feed-forward clock support first appeared in +.Fx 10.0 . +.Sh AUTHORS +.An -nosplit +The feed-forward clock support was written by +.An Julien Ridoux Aq Mt jridoux@unimelb.edu.au +in collaboration with +.An Darryl Veitch Aq Mt dveitch@unimelb.edu.au +at the University of Melbourne under sponsorship from the FreeBSD Foundation. diff --git a/lib/libsys/fhlink.2 b/lib/libsys/fhlink.2 new file mode 100644 index 000000000000..b7f7d02dd136 --- /dev/null +++ b/lib/libsys/fhlink.2 @@ -0,0 +1,254 @@ +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2018 Gandi +.\" +.\" 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. +.\" +.Dd November 30, 2022 +.Dt FHLINK 2 +.Os +.Sh NAME +.Nm fhlink , +.Nm fhlinkat +.Nd make a hard file link +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn fhlink "fhandle_t *fhp" "const char *to" +.Ft int +.Fn fhlinkat "fhandle_t *fhp" "int tofd" "const char *to" +.Sh DESCRIPTION +The +.Fn fhlink +system call +atomically creates the specified directory entry (hard link) +.Fa to +with the attributes of the underlying object pointed at by +.Fa fhp . +If the link is successful: the link count of the underlying object +is incremented; +.Fa fhp +and +.Fa to +share equal access and rights +to the +underlying object. +.Pp +If +.Fa fhp +is removed, the file +.Fa to +is not deleted and the link count of the +underlying object is +decremented. +.Pp +The object pointed at by the +.Fa fhp +argument +must exist for the hard link to +succeed and +both +.Fa fhp +and +.Fa to +must be in the same file system. +The +.Fa fhp +argument +may not be a directory. +.Pp +The +.Fn fhlinkat +system call is equivalent to +.Fa fhlink +except in the case where +.Fa to +is a relative paths. +In this case a relative path +.Fa to +is interpreted relative to +the directory associated with the file descriptor +.Fa tofd +instead of the current working directory. +.Pp +If +.Fn fhlinkat +is passed the special value +.Dv AT_FDCWD +in the +.Fa tofd +parameter, the current working directory is used for the +.Fa to +argument. +If +.Fa tofd +has value +.Dv AT_FDCWD , +the behavior is identical to a call to +.Fn link . +Unless +.Fa flag +contains the +.Dv AT_SYMLINK_FOLLOW +flag, if +.Fa fhp +names a symbolic link, a new link is created for the symbolic link +.Fa fhp +and not its target. +.Sh RETURN VALUES +.Rv -std link +.Sh ERRORS +The +.Fn fhlink +system call +will fail and no link will be created if: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of +.Fa to +prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of +.Fa to +exceeded 255 characters, +or entire length of +.Fa to +name exceeded 1023 characters. +.It Bq Er ENOENT +A component of +.Fa to +prefix does not exist. +.It Bq Er EOPNOTSUPP +The file system containing the file pointed at by +.Fa fhp +does not support links. +.It Bq Er EMLINK +The link count of the file pointed at by +.Fa fhp +would exceed 32767. +.It Bq Er EACCES +A component of +.Fa to +prefix denies search permission. +.It Bq Er EACCES +The requested link requires writing in a directory with a mode +that denies write permission. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating one of the pathnames. +.It Bq Er ENOENT +The file pointed at by +.Fa fhp +does not exist. +.It Bq Er EEXIST +The link named by +.Fa to +does exist. +.It Bq Er EPERM +The file pointed at by +.Fa fhp +is a directory. +.It Bq Er EPERM +The file pointed at by +.Fa fhp +has its immutable or append-only flag set, see the +.Xr chflags 2 +manual page for more information. +.It Bq Er EPERM +The parent directory of the file named by +.Fa to +has its immutable flag set. +.It Bq Er EXDEV +The link named by +.Fa to +and the file pointed at by +.Fa fhp +are on different file systems. +.It Bq Er ENOSPC +The directory in which the entry for the new link is being placed +cannot be extended because there is no space left on the file +system containing the directory. +.It Bq Er EDQUOT +The directory in which the entry for the new link +is being placed cannot be extended because the +user's quota of disk blocks on the file system +containing the directory has been exhausted. +.It Bq Er EIO +An I/O error occurred while reading from or writing to +the file system to make the directory entry. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.It Bq Er EROFS +The requested link requires writing in a directory on a read-only file +system. +.It Bq Er EFAULT +One of the pathnames specified +is outside the process's allocated address space. +.It Bq Er ESTALE +The file handle +.Fa fhp +is no longer valid +.El +.Pp +In addition to the errors returned by the +.Fn fhlink , +the +.Fn fhlinkat +system call may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fhp +or +.Fa to +argument does not specify an absolute path and the +.Fa tofd +argument, is not +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er EINVAL +The value of the +.Fa flag +argument is not valid. +.It Bq Er ENOTDIR +The +.Fa fhp +or +.Fa to +argument is not an absolute path and +.Fa tofd +is not +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El +.Sh SEE ALSO +.Xr fhopen 2 , +.Xr fhreadlink 2 , +.Xr fhstat 2 +.Sh HISTORY +The +.Fn fhlink +and +.Fn fhlinkat +system calls first appeared in +.Fx 12.1 . diff --git a/lib/libsys/fhopen.2 b/lib/libsys/fhopen.2 new file mode 100644 index 000000000000..b281ac3d8949 --- /dev/null +++ b/lib/libsys/fhopen.2 @@ -0,0 +1,160 @@ +.\" $NetBSD: fhopen.2,v 1.1 1999/06/30 01:32:15 wrstuden Exp $ +.\" +.\" Copyright (c) 1999 National Aeronautics & Space Administration +.\" All rights reserved. +.\" +.\" This software was written by William Studenmund of the +.\" Numerical Aerospace Simulation Facility, NASA Ames Research Center. +.\" +.\" 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. +.\" 3. Neither the name of the National Aeronautics & Space Administration +.\" nor the names of its contributors may be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NATIONAL AERONAUTICS & SPACE ADMINISTRATION +.\" ``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 ADMINISTRATION OR CONTRIB- +.\" UTORS 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. +.\" +.Dd July 20, 2025 +.Dt FHOPEN 2 +.Os +.Sh NAME +.Nm fhopen , +.Nm fhstat , +.Nm fhstatfs +.Nd access file via file handle +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.In sys/stat.h +.Ft int +.Fn fhopen "const fhandle_t *fhp" "int flags" +.Ft int +.Fn fhstat "const fhandle_t *fhp" "struct stat *sb" +.Ft int +.Fn fhstatfs "const fhandle_t *fhp" "struct statfs *buf" +.Sh DESCRIPTION +These system calls provide a means to access a file given the file handle +.Fa fhp . +As this method bypasses directory access restrictions, these calls are +restricted to the superuser. +.Pp +The +.Fn fhopen +system call +opens the file referenced by +.Fa fhp +for reading and/or writing as specified by the argument +.Fa flags +and returns the file descriptor to the calling process. +The +.Fa flags +argument +is specified by +.Em or Ns 'ing +together the flags used for the +.Xr open 2 +system call. +All said flags are valid except for +.Dv O_CREAT . +If the file handle refers to a named attribute or named attribute +directory, the +.Dv O_NAMEDATTR +flag must be specified. +.Pp +The +.Fn fhstat +and +.Fn fhstatfs +system calls +provide the functionality of the +.Xr fstat 2 +and +.Xr fstatfs 2 +calls except that they return information for the file referred to by +.Fa fhp +rather than an open file. +.Sh RETURN VALUES +Upon successful completion, +.Fn fhopen +returns the file descriptor for the opened file; +otherwise the value \-1 is returned and the global variable +.Va errno +is set to indicate the error. +.Pp +.Rv -std fhstat fhstatfs +.Sh ERRORS +In addition to the errors returned by +.Xr open 2 , +.Xr fstat 2 , +and +.Xr fstatfs 2 +respectively, +.Fn fhopen , +.Fn fhstat , +and +.Fn fhstatfs +will return +.Bl -tag -width Er +.It Bq Er EINVAL +Calling +.Fn fhopen +with +.Dv O_CREAT +set. +.It Bq Er ENOATTR +The file handle does not refer to a named attribute or named attribute +directory although the +.Dv O_NAMEDATTR +flag was specified. +.It Bq Er ENOATTR +The file handle refers to a named attribute or named attribute directory +although the +.Dv O_NAMEDATTR +flag was not specified. +.It Bq Er ESTALE +The file handle +.Fa fhp +is no longer valid. +.El +.Sh SEE ALSO +.Xr fstat 2 , +.Xr fstatfs 2 , +.Xr getfh 2 , +.Xr open 2 , +.Xr named_attribute 7 +.Sh HISTORY +The +.Fn fhopen , +.Fn fhstat , +and +.Fn fhstatfs +system calls first appeared in +.Nx 1.5 +and were adapted to +.Fx 4.0 +by +.An Alfred Perlstein . +.Sh AUTHORS +This manual page was written by +.An William Studenmund +for +.Nx . diff --git a/lib/libsys/fhreadlink.2 b/lib/libsys/fhreadlink.2 new file mode 100644 index 000000000000..4855f4d8ec67 --- /dev/null +++ b/lib/libsys/fhreadlink.2 @@ -0,0 +1,96 @@ +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2018 Gandi +.\" +.\" 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. +.\" +.Dd November 30, 2022 +.Dt FHREADLINK 2 +.Os +.Sh NAME +.Nm fhreadlink +.Nd read value of a symbolic link +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.Ft int +.Fn fhreadlink "fhandle_t *fhp" "char *buf" "size_t bufsize" +.Sh DESCRIPTION +The +.Fn fhreadlink +system call +places the contents of the symbolic link +.Fa fhp +in the buffer +.Fa buf , +which has size +.Fa bufsiz . +The +.Fn fhreadlink +system call does not append a +.Dv NUL +character to +.Fa buf . +.Pp +.Sh RETURN VALUES +The call returns the count of characters placed in the buffer +if it succeeds, or a \-1 if an error occurs, placing the error +code in the global variable +.Va errno . +.Sh ERRORS +The +.Fn fhreadlink +system call +will fail if: +.Bl -tag -width Er +.It Bq Er ENOENT +The named file does not exist. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the file handle +.Fa fhp . +.It Bq Er EINVAL +The named file is not a symbolic link. +.It Bq Er EIO +An I/O error occurred while reading from the file system. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.It Bq Er EFAULT +The +.Fa buf +argument +extends outside the process's allocated address space. +.It Bq Er ESTALE +The file handle +.Fa fhp +is no longer valid +.El +.Sh SEE ALSO +.Xr fhlink 2 , +.Xr fhstat 2 , +.Xr readlink 2 +.Sh HISTORY +The +.Fn fhreadlink +system call first appeared in +.Fx 12.1 . diff --git a/lib/libsys/flock.2 b/lib/libsys/flock.2 new file mode 100644 index 000000000000..f1a989a1d484 --- /dev/null +++ b/lib/libsys/flock.2 @@ -0,0 +1,170 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd November 9, 2011 +.Dt FLOCK 2 +.Os +.Sh NAME +.Nm flock +.Nd "apply or remove an advisory lock on an open file" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/file.h +.Fd "#define LOCK_SH 0x01 /* shared file lock */" +.Fd "#define LOCK_EX 0x02 /* exclusive file lock */" +.Fd "#define LOCK_NB 0x04 /* do not block when locking */" +.Fd "#define LOCK_UN 0x08 /* unlock file */" +.Ft int +.Fn flock "int fd" "int operation" +.Sh DESCRIPTION +The +.Fn flock +system call applies or removes an +.Em advisory +lock on the file associated with the file descriptor +.Fa fd . +A lock is applied by specifying an +.Fa operation +argument that is one of +.Dv LOCK_SH +or +.Dv LOCK_EX +with the optional addition of +.Dv LOCK_NB . +To unlock +an existing lock +.Dv operation +should be +.Dv LOCK_UN . +.Pp +Advisory locks allow cooperating processes to perform +consistent operations on files, but do not guarantee +consistency (i.e., processes may still access files +without using advisory locks possibly resulting in +inconsistencies). +.Pp +The locking mechanism allows two types of locks: +.Em shared +locks and +.Em exclusive +locks. +At any time multiple shared locks may be applied to a file, +but at no time are multiple exclusive, or both shared and exclusive, +locks allowed simultaneously on a file. +.Pp +A shared lock may be +.Em upgraded +to an exclusive lock, and vice versa, simply by specifying +the appropriate lock type; this results in the previous +lock being released and the new lock applied (possibly +after other processes have gained and released the lock). +.Pp +Requesting a lock on an object that is already locked +normally causes the caller to be blocked until the lock may be +acquired. +If +.Dv LOCK_NB +is included in +.Fa operation , +then this will not happen; instead the call will fail and +the error +.Er EWOULDBLOCK +will be returned. +.Sh NOTES +Locks are on files, not file descriptors. +That is, file descriptors +duplicated through +.Xr dup 2 +or +.Xr fork 2 +do not result in multiple instances of a lock, but rather multiple +references to a single lock. +If a process holding a lock on a file +forks and the child explicitly unlocks the file, the parent will +lose its lock. +.Pp +The +.Fn flock , +.Xr fcntl 2 , +and +.Xr lockf 3 +locks are compatible. +Processes using different locking interfaces can cooperate +over the same file safely. +However, only one of such interfaces should be used within +the same process. +If a file is locked by a process through +.Fn flock , +any record within the file will be seen as locked +from the viewpoint of another process using +.Xr fcntl 2 +or +.Xr lockf 3 , +and vice versa. +.Pp +Processes blocked awaiting a lock may be awakened by signals. +.Sh RETURN VALUES +.Rv -std flock +.Sh ERRORS +The +.Fn flock +system call fails if: +.Bl -tag -width Er +.It Bq Er EWOULDBLOCK +The file is locked and the +.Dv LOCK_NB +option was specified. +.It Bq Er EBADF +The argument +.Fa fd +is an invalid descriptor. +.It Bq Er EINVAL +The argument +.Fa fd +refers to an object other than a file. +.It Bq Er EOPNOTSUPP +The argument +.Fa fd +refers to an object that does not support file locking. +.It Bq Er ENOLCK +A lock was requested, but no locks are available. +.El +.Sh SEE ALSO +.Xr close 2 , +.Xr dup 2 , +.Xr execve 2 , +.Xr fcntl 2 , +.Xr fork 2 , +.Xr open 2 , +.Xr flopen 3 , +.Xr lockf 3 +.Sh HISTORY +The +.Fn flock +system call appeared in +.Bx 4.2 . diff --git a/lib/libsys/fork.2 b/lib/libsys/fork.2 new file mode 100644 index 000000000000..e59b208a9ff5 --- /dev/null +++ b/lib/libsys/fork.2 @@ -0,0 +1,278 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd May 17, 2024 +.Dt FORK 2 +.Os +.Sh NAME +.Nm fork +.Nd create a new process +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft pid_t +.Fn fork void +.Ft pid_t +.Fn _Fork void +.Sh DESCRIPTION +The +.Fn fork +function causes creation of a new process. +The new process (child process) is an exact copy of the +calling process (parent process) except for the following: +.Bl -bullet -offset indent +.It +The child process has a unique process ID. +.It +The child process has a different parent +process ID (i.e., the process ID of the parent process). +.It +The child process has its own copy of the parent's descriptors, +except for descriptors returned by +.Xr kqueue 2 , +which are not inherited from the parent process. +These descriptors reference the same underlying objects, so that, +for instance, file pointers in file objects are shared between +the child and the parent, so that an +.Xr lseek 2 +on a descriptor in the child process can affect a subsequent +.Xr read 2 +or +.Xr write 2 +by the parent. +This descriptor copying is also used by the shell to +establish standard input and output for newly created processes +as well as to set up pipes. +Any file descriptors that were marked with the close-on-fork flag, +.Dv FD_CLOFORK +.Po see +.Fn fcntl 2 +and +.Dv O_CLOFORK +in +.Fn open 2 +.Pc , +will not be present in the child process, but remain open in the parent. +.It +The child process' resource utilizations +are set to 0; see +.Xr setrlimit 2 . +.It +All interval timers are cleared; see +.Xr setitimer 2 . +.It +The robust mutexes list (see +.Xr pthread_mutexattr_setrobust 3 ) +is cleared for the child. +.It +The atfork handlers established with the +.Xr pthread_atfork 3 +function are called as appropriate before fork in the parent process, +and after the child is created, in parent and child. +.It +The child process has only one thread, +corresponding to the calling thread in the parent process. +If the process has more than one thread, +locks and other resources held by the other threads are not released +and therefore only async-signal-safe functions +(see +.Xr sigaction 2 ) +are guaranteed to work in the child process until a call to +.Xr execve 2 +or a similar function. +The +.Fx +implementation of +.Fn fork +provides a usable +.Xr malloc 3 , +and +.Xr rtld 1 +services in the child process. +.El +.Pp +The +.Fn fork +function is not async-signal safe and creates a cancellation point +in the parent process. +It cannot be safely used from signal handlers, and the atfork handlers +established by +.Xr pthread_atfork 3 +do not need to be async-signal safe either. +.Pp +The +.Fn _Fork +function creates a new process, similarly to +.Fn fork , +but it is async-signal safe. +.Fn _Fork +does not call atfork handlers, and does not create a cancellation point. +It can be used safely from signal handlers, but then no userspace +services ( +.Xr malloc 3 +or +.Xr rtld 1 ) +are available in the child if forked from multi-threaded parent. +In particular, if using dynamic linking, all dynamic symbols used by the +child after +.Fn _Fork +must be pre-resolved. +Note: resolving can be done globally by specifying the +.Ev LD_BIND_NOW +environment variable to the dynamic linker, or per-binary by passing the +.Fl z Ar now +option to the static linker +.Xr ld 1 , +or by using each symbol before the +.Fn _Fork +call to force the binding. +.Sh RETURN VALUES +Upon successful completion, +.Fn fork +and +.Fn _Fork +return a value +of 0 to the child process and return the process ID of the child +process to the parent process. +Otherwise, a value of -1 is returned +to the parent process, no child process is created, and the global +variable +.Va errno +is set to indicate the error. +.Sh EXAMPLES +The following example shows a common pattern of how +.Fn fork +is used in practice. +.Bd -literal -offset indent +#include <err.h> +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> + +int +main(void) +{ + pid_t pid; + + /* + * If child is expected to use stdio(3), state of + * the reused io streams must be synchronized between + * parent and child, to avoid double output and other + * possible issues. + */ + fflush(stdout); + + switch (pid = fork()) { + case -1: + err(1, "Failed to fork"); + case 0: + printf("Hello from child process!\en"); + + /* + * Since we wrote into stdout, child needs to use + * exit(3) and not _exit(2). This causes handlers + * registered with atexit(3) to be called twice, + * once in parent, and once in the child. If such + * behavior is undesirable, consider + * terminating child with _exit(2) or _Exit(3). + */ + exit(0); + default: + break; + } + + printf("Hello from parent process (child's PID: %d)!\en", pid); + + return (0); +} +.Ed +.Pp +The output of such a program is along the lines of: +.Bd -literal -offset indent +Hello from parent process (child's PID: 27804)! +Hello from child process! +.Ed +.Sh ERRORS +The +.Fn fork +system call will fail and no child process will be created if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The system-imposed limit on the total +number of processes under execution would be exceeded. +The limit is given by the +.Xr sysctl 3 +MIB variable +.Dv KERN_MAXPROC . +(The limit is actually ten less than this +except for the super user). +.It Bq Er EAGAIN +The user is not the super user, and +the system-imposed limit +on the total number of +processes under execution by a single user would be exceeded. +The limit is given by the +.Xr sysctl 3 +MIB variable +.Dv KERN_MAXPROCPERUID . +.It Bq Er EAGAIN +The user is not the super user, and +the soft resource limit corresponding to the +.Fa resource +argument +.Dv RLIMIT_NPROC +would be exceeded (see +.Xr getrlimit 2 ) . +.It Bq Er ENOMEM +There is insufficient swap space for the new process. +.El +.Sh SEE ALSO +.Xr execve 2 , +.Xr rfork 2 , +.Xr setitimer 2 , +.Xr setrlimit 2 , +.Xr sigaction 2 , +.Xr vfork 2 , +.Xr wait 2 , +.Xr pthread_atfork 3 +.Sh STANDARDS +The +.Fn fork +and +.Fn _Fork +functions conform to +.St -p1003.1-2024 . +.Sh HISTORY +The +.Fn fork +function appeared in +.At v1 . +The +.Fn _Fork +function appeared in +.Fx 13.1 . diff --git a/lib/libsys/fspacectl.2 b/lib/libsys/fspacectl.2 new file mode 100644 index 000000000000..911c24101785 --- /dev/null +++ b/lib/libsys/fspacectl.2 @@ -0,0 +1,205 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2021 The FreeBSD Foundation +.\" +.\" This manual page was written by Ka Ho Ng under sponsorship from +.\" the FreeBSD Foundation. +.\" +.\" 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. +.\" +.Dd August 25, 2021 +.Dt FSPACECTL 2 +.Os +.Sh NAME +.Nm fspacectl +.Nd space management in a file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In fcntl.h +.Ft int +.Fo fspacectl +.Fa "int fd" +.Fa "int cmd" +.Fa "const struct spacectl_range *rqsr" +.Fa "int flags" +.Fa "struct spacectl_range *rmsr" +.Fc +.Sh DESCRIPTION +.Nm +is a system call performing space management over a file. +The +.Fa fd +argument specifies the file descriptor to be operated on by the +.Fa cmd +argument. +The +.Fa rqsr +argument points to a +.Fa spacectl_range +structure that contains the requested operation range. +The +.Fa flags +argument controls the behavior of the operation to take place. +If the +.Fa rmsr +argument is non-NULL, the +.Fa spacectl_range +structure it points to is updated to contain the unprocessed operation range +after the system call returns. +.Pp +For a successful completion without an unprocessed part in the requested +operation range, +.Fa "rmsr->r_len" +is updated to be the value 0, and +.Fa "rmsr->r_offset" +is updated to be +.Fa "rqsr->r_offset" +plus the number of bytes zeroed before the end-of-file. +The file descriptor's file offset is not used or modified by the system call. +Both +.Fa rqsr +and +.Fa rmsr +arguments can point to the same structure. +.Pp +The +.Fa spacectl_range +structure is defined as: +.Bd -literal +struct spacectl_range { + off_t r_offset; + off_t r_len; +}; +.Ed +.Pp +The operation specified by the +.Fa cmd +argument may be one of: +.Bl -tag -width SPACECTL_DEALLOC +.It Dv SPACECTL_DEALLOC +Zero a region in the file specified by the +.Fa rqsr +argument. +The +.Fa "rqsr->r_offset" +has to be a value greater than or equal to 0, and the +.Fa "rqsr->r_len" +has to be a value greater than 0. +.Pp +If the file system supports hole-punching, +file system space deallocation may be performed in the given region. +.El +.Pp +The +.Fa flags +argument needs to be the value 0 currently. +.Sh RETURN VALUES +Upon successful completion, the value 0 is returned; +otherwise the value -1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +Possible failure conditions: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid file descriptor. +.It Bq Er EBADF +The +.Fa fd +argument references a file that was opened without write permission. +.It Bq Er EINTR +A signal was caught during execution. +.It Bq Er EINVAL +The +.Fa cmd +argument is not valid. +.It Bq Er EINVAL +If the +.Fa cmd +argument is +.Dv SPACECTL_DEALLOC , +either the +.Fa "rqsr->r_offset" +argument was less than zero, or the +.Fa "rqsr->r_len" +argument was less than or equal to zero. +.It Bq Er EINVAL +The value of +.Fa "rqsr->r_offset" + +.Fa "rqsr->r_len" +is greater than +.Dv OFF_MAX . +.It Bq Er EINVAL +An invalid or unsupported flag is included in +.Fa flags . +.It Bq Er EINVAL +A flag included in +.Fa flags +is not supported by the operation specified by the +.Fa cmd +argument. +.It Bq Er EFAULT +The +.Fa rqsr +or a non-NULL +.Fa rmsr +argument point outside the process' allocated address space. +.It Bq Er EIO +An I/O error occurred while reading from or writing to a file system. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.It Bq Er ENODEV +The +.Fa fd +argument does not refer to a file that supports +.Nm . +.It Bq Er ENOSPC +There is insufficient free space remaining on the file system storage +media. +.It Bq Er ENOTCAPABLE +The file descriptor +.Fa fd +has insufficient rights. +.It Bq Er ESPIPE +The +.Fa fd +argument is associated with a pipe or FIFO. +.El +.Sh SEE ALSO +.Xr creat 2 , +.Xr ftruncate 2 , +.Xr open 2 , +.Xr unlink 2 +.Sh HISTORY +The +.Nm +system call appeared in +.Fx 14.0 . +.Sh AUTHORS +.Nm +and this manual page were written by +.An Ka Ho Ng Aq Mt khng@FreeBSD.org +under sponsorship from the FreeBSD Foundation. diff --git a/lib/libsys/fsync.2 b/lib/libsys/fsync.2 new file mode 100644 index 000000000000..d05c078af1e6 --- /dev/null +++ b/lib/libsys/fsync.2 @@ -0,0 +1,130 @@ +.\" Copyright (c) 1983, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" Copyright (c) 2016 The FreeBSD Foundation +.\" +.\" Parts of this documentation were written by +.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd March 30, 2020 +.Dt FSYNC 2 +.Os +.Sh NAME +.Nm fdatasync , +.Nm fsync +.Nd "synchronise changes to a file" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn fdatasync "int fd" +.Ft int +.Fn fsync "int fd" +.Sh DESCRIPTION +The +.Fn fsync +system call +causes all modified data and attributes of the file referenced by +the file descriptor +.Fa fd +to be moved to a permanent storage device. +This normally results in all in-core modified copies +of buffers for the associated file to be written to a disk. +.Pp +The +.Fn fdatasync +system call causes all modified data of +.Fa fd +to be moved to a permanent storage device. +Unlike +.Fn fsync , +the system call does not guarantee that file attributes or +metadata necessary to access the file are committed to the permanent storage. +.Pp +The +.Fn fsync +system call +should be used by programs that require a file to be +in a known state, for example, in building a simple transaction +facility. +If the file metadata has already been committed, using +.Fn fdatasync +can be more efficient than +.Fn fsync . +.Pp +Both +.Fn fdatasync +and +.Fn fsync +calls are cancellation points. +.Sh RETURN VALUES +.Rv -std fsync +.Sh ERRORS +The +.Fn fsync +and +.Fn fdatasync +calls fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument +is not a valid descriptor. +.It Bq Er EINVAL +The +.Fa fd +argument +refers to a socket, not to a file. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.El +.Sh SEE ALSO +.Xr fsync 1 , +.Xr sync 2 , +.Xr syncer 4 , +.Xr sync 8 +.Sh HISTORY +The +.Fn fsync +system call appeared in +.Bx 4.2 . +The +.Fn fdatasync +system call appeared in +.Fx 11.1 . +.Sh BUGS +The +.Fn fdatasync +system call currently does not guarantee that enqueued +.Xr aio 4 +requests for the file referenced by +.Fa fd +are completed before the syscall returns. diff --git a/lib/libsys/getdirentries.2 b/lib/libsys/getdirentries.2 new file mode 100644 index 000000000000..202ae133f548 --- /dev/null +++ b/lib/libsys/getdirentries.2 @@ -0,0 +1,211 @@ +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd July 8, 2025 +.Dt GETDIRENTRIES 2 +.Os +.Sh NAME +.Nm getdirentries , +.Nm getdents +.Nd "get directory entries in a file system independent format" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In dirent.h +.Ft ssize_t +.Fn getdirentries "int fd" "char *buf" "size_t nbytes" "off_t *basep" +.Ft ssize_t +.Fn getdents "int fd" "char *buf" "size_t nbytes" +.Sh DESCRIPTION +The +.Fn getdirentries +and +.Fn getdents +system calls read directory entries from the directory +referenced by the file descriptor +.Fa fd +into the buffer pointed to by +.Fa buf , +in a file system independent format. +Up to +.Fa nbytes +of data will be transferred. +The +.Fa nbytes +argument must be greater than or equal to the +block size associated with the file, +see +.Xr stat 2 . +Some file systems may not support these system calls +with buffers smaller than this size. +.Pp +The data in the buffer is a series of +.Vt dirent +structures each containing the following entries: +.Bd -literal -offset indent +ino_t d_fileno; +off_t d_off; +uint16_t d_reclen; +uint8_t d_type; +uint16_t d_namlen; +char d_name[MAXNAMLEN + 1]; /* see below */ +.Ed +.Pp +The +.Fa d_fileno +entry is a number which is unique for each +distinct file in the file system. +Files that are linked by hard links (see +.Xr link 2 ) +have the same +.Fa d_fileno . +The +.Fa d_off +field returns a cookie which, if non-zero, can be used with +.Xr lseek 2 +to position the directory descriptor to the next entry. +The +.Fa d_reclen +entry is the length, in bytes, of the directory record. +The +.Fa d_type +entry is the type of the file pointed to by the directory record. +The file type values are defined in +.Fa <sys/dirent.h> . +The +.Fa d_name +entry contains a null terminated file name. +The +.Fa d_namlen +entry specifies the length of the file name excluding the null byte. +Thus the actual size of +.Fa d_name +may vary from 1 to +.Dv MAXNAMLEN +\&+ 1. +.Pp +Entries may be separated by extra space. +The +.Fa d_reclen +entry may be used as an offset from the start of a +.Fa dirent +structure to the next structure, if any. +.Pp +The actual number of bytes transferred is returned. +The current position pointer associated with +.Fa fd +is set to point to the next block of entries. +The pointer may not advance by the number of bytes returned by +.Fn getdirentries +or +.Fn getdents . +A value of zero is returned when +the end of the directory has been reached. +.Pp +If the +.Fa basep +pointer value is non-NULL, +the +.Fn getdirentries +system call writes the position of the block read into the location pointed to by +.Fa basep . +Alternatively, the current position pointer may be set and retrieved by +.Xr lseek 2 . +The current position pointer should only be set to a value returned by +.Xr lseek 2 , +a value returned in the location pointed to by +.Fa basep +.Po Fn getdirentries +only +.Pc , +a value returned in the +.Fa d_off +field if it is non-zero, +or zero. +.Sh IMPLEMENTATION NOTES +The +.Fa d_off +field is currently set to 0 by the NFS client, since the +directory offset cookies returned by an NFS server cannot +be used by +.Xr lseek 2 +at this time. +.Sh RETURN VALUES +If successful, the number of bytes actually transferred is returned. +Otherwise, -1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn getdirentries +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument +is not a valid file descriptor open for reading. +.It Bq Er EFAULT +Either +.Fa buf +or non-NULL +.Fa basep +point outside the allocated address space. +.It Bq Er EINVAL +The value of +.Fa nbytes +is too small for returning a directory entry or block of entries, +or the current position pointer is invalid. +.It Bq Er EIO +An +.Tn I/O +error occurred while reading from or writing to the file system. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.It Bq Er ENOENT +Directory unlinked but still open. +.It Bq Er ENOTDIR +The file referenced by +.Fa fd +is not a directory. +.El +.Sh SEE ALSO +.Xr lseek 2 , +.Xr open 2 , +.Xr directory 3 , +.Xr dir 5 +.Sh HISTORY +The +.Fn getdirentries +system call first appeared in +.Bx 4.4 . +The +.Fn getdents +system call first appeared in +.Fx 3.0 . diff --git a/lib/libsys/getdtablesize.2 b/lib/libsys/getdtablesize.2 new file mode 100644 index 000000000000..c4504bcd7a35 --- /dev/null +++ b/lib/libsys/getdtablesize.2 @@ -0,0 +1,59 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd April 24, 2013 +.Dt GETDTABLESIZE 2 +.Os +.Sh NAME +.Nm getdtablesize +.Nd get file descriptor limit +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn getdtablesize void +.Sh DESCRIPTION +The +.Fn getdtablesize +system call returns the maximum number of file descriptors +that the current process may open. +The maximum file descriptor number that the system may assign +is the return value minus one. +Existing file descriptor numbers may be higher +if the limit was lowered after they were opened. +.Sh SEE ALSO +.Xr close 2 , +.Xr closefrom 2 , +.Xr dup 2 , +.Xr getrlimit 2 , +.Xr sysconf 3 +.Sh HISTORY +The +.Fn getdtablesize +system call appeared in +.Bx 4.2 . diff --git a/lib/libsys/getfh.2 b/lib/libsys/getfh.2 new file mode 100644 index 000000000000..d16a34da4f28 --- /dev/null +++ b/lib/libsys/getfh.2 @@ -0,0 +1,232 @@ +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" Copyright (c) 2018 Gandi +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd November 30, 2022 +.Dt GETFH 2 +.Os +.Sh NAME +.Nm getfh , +.Nm lgetfh , +.Nm getfhat +.Nd get file handle +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.Ft int +.Fn getfh "const char *path" "fhandle_t *fhp" +.Ft int +.Fn lgetfh "const char *path" "fhandle_t *fhp" +.Ft int +.Fn getfhat "int fd" "const char *path" "fhandle_t *fhp" "int flag" +.Sh DESCRIPTION +The +.Fn getfh +system call +returns a file handle for the specified file or directory +in the file handle pointed to by +.Fa fhp . +.Pp +The +.Fn lgetfh +system call is like +.Fn getfh +except in the case where the named file is a symbolic link, +in which case +.Fn lgetfh +returns information about the link, +while +.Fn getfh +returns information about the file the link references. +.Pp +The +.Fn getfhat +system call is equivalent to +.Fn getfh +and +.Fn lgetfh +except when the +.Fa path +specifies a relative path. +For +.Fn getfhat +and relative +.Fa path , +the status is retrieved from a file relative to +the directory associated with the file descriptor +.Fa fd +instead of the current working directory. +.Pp +The values for the +.Fa flag +are constructed by a bitwise-inclusive OR of flags from this list, +defined in +.In fcntl.h : +.Bl -tag -width indent +.It Dv AT_SYMLINK_NOFOLLOW +If +.Fa path +names a symbolic link, the status of the symbolic link is returned. +.It Dv AT_RESOLVE_BENEATH +Only walk paths below the directory specified by the +.Ar fd +descriptor. +See the description of the +.Dv O_RESOLVE_BENEATH +flag in the +.Xr open 2 +manual page. +.El +.Pp +If +.Fn getfhat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is +identical to a call to +.Fn getfth +or +.Fn lgetfh +respectively, depending on whether or not the +.Dv AT_SYMLINK_NOFOLLOW +bit is set in +.Fa flag . +.Pp +When +.Fn getfhat +is called with an absolute +.Fa path , +it ignores the +.Fa fd +argument. +.Pp +These system calls are restricted to the superuser. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn getfh +and +.Fn lgetfh +system calls +fail if one or more of the following are true: +.Bl -tag -width Er +.It Bq Er EPERM +The caller does not have appropriate privilege to perform the operation. +.It Bq Er ENOTDIR +A component of the path prefix of +.Fa path +is not a directory. +.It Bq Er ENAMETOOLONG +The length of a component of +.Fa path +exceeds 255 characters, +or the length of +.Fa path +exceeds 1023 characters. +.It Bq Er ENOENT +The file referred to by +.Fa path +does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix of +.Fa path . +.It Bq Er ELOOP +Too many symbolic links were encountered in translating +.Fa path . +.It Bq Er EFAULT +The +.Fa fhp +argument +points to an invalid address. +.It Bq Er EFAULT +The +.Fa path +argument +points to an invalid address. +.It Bq Er EIO +An +.Tn I/O +error occurred while reading from or writing to the file system. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.It Bq Er ESTALE +The file handle +.Fa fhp +is no longer valid. +.El +.Pp +In addition to the errors returned by +.Fn getfh , +and +.Fn lgetfh , +the +.Fn getfhat +system call may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument, is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er EINVAL +The value of the +.Fa flag +argument is not valid. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El +.Sh SEE ALSO +.Xr fhopen 2 , +.Xr open 2 , +.Xr stat 2 +.Sh HISTORY +The +.Fn getfh +system call first appeared in +.Bx 4.4 . +The +.Fn lgetfh +system call first appeared in +.Fx 5.3 . +The +.Fn getfhat +system call first appeared in +.Fx 12.1 . diff --git a/lib/libsys/getfsstat.2 b/lib/libsys/getfsstat.2 new file mode 100644 index 000000000000..91a3a10117dc --- /dev/null +++ b/lib/libsys/getfsstat.2 @@ -0,0 +1,129 @@ +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd March 30, 2020 +.Dt GETFSSTAT 2 +.Os +.Sh NAME +.Nm getfsstat +.Nd get list of all mounted file systems +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/ucred.h +.In sys/mount.h +.Ft int +.Fn getfsstat "struct statfs *buf" "long bufsize" "int mode" +.Sh DESCRIPTION +The +.Fn getfsstat +system call +returns information about all mounted file systems. +The +.Fa buf +argument +is a pointer to +.Vt statfs +structures, as described in +.Xr statfs 2 . +.Pp +Fields that are undefined for a particular file system are set to -1. +The buffer is filled with an array of +.Fa statfs +structures, one for each mounted file system +up to the byte count specified by +.Fa bufsize . +Note, the +.Fa bufsize +argument is the number of bytes that +.Fa buf +can hold, not the count of statfs structures it will hold. +.Pp +If +.Fa buf +is given as NULL, +.Fn getfsstat +returns just the number of mounted file systems. +.Pp +Normally +.Fa mode +should be specified as +.Dv MNT_WAIT . +If +.Fa mode +is set to +.Dv MNT_NOWAIT , +.Fn getfsstat +will return the information it has available without requesting +an update from each file system. +Thus, some of the information will be out of date, but +.Fn getfsstat +will not block waiting for information from a file system that is +unable to respond. +It will also skip any file system that is in the process of being +unmounted, even if the unmount would eventually fail. +.Sh RETURN VALUES +Upon successful completion, the number of +.Fa statfs +structures is returned. +Otherwise, -1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn getfsstat +system call +fails if one or more of the following are true: +.Bl -tag -width Er +.It Bq Er EFAULT +The +.Fa buf +argument +points to an invalid address. +.It Bq Er EINVAL +.Fa mode +is set to a value other than +.Dv MNT_WAIT +or +.Dv MNT_NOWAIT . +.It Bq Er EIO +An +.Tn I/O +error occurred while reading from or writing to the file system. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.El +.Sh SEE ALSO +.Xr statfs 2 , +.Xr fstab 5 , +.Xr mount 8 +.Sh HISTORY +The +.Fn getfsstat +system call first appeared in +.Bx 4.4 . diff --git a/lib/libsys/getgid.2 b/lib/libsys/getgid.2 new file mode 100644 index 000000000000..ea10e8322d1f --- /dev/null +++ b/lib/libsys/getgid.2 @@ -0,0 +1,82 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd May 1, 2020 +.Dt GETGID 2 +.Os +.Sh NAME +.Nm getgid , +.Nm getegid +.Nd get group process identification +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft gid_t +.Fn getgid void +.Ft gid_t +.Fn getegid void +.Sh DESCRIPTION +The +.Fn getgid +system call returns the real group ID of the calling process, +.Fn getegid +returns the effective group ID of the calling process. +.Pp +The real group ID is specified at login time. +.Pp +The real group ID is the group of the user who invoked the program. +As the effective group ID gives the process additional permissions +during the execution of +.Dq Em set-group-ID +mode processes, +.Fn getgid +is used to determine the real-user-id of the calling process. +.Sh ERRORS +The +.Fn getgid +and +.Fn getegid +system calls are always successful, and no return value is reserved to +indicate an error. +.Sh SEE ALSO +.Xr getuid 2 , +.Xr issetugid 2 , +.Xr setgid 2 , +.Xr setregid 2 +.Sh STANDARDS +The +.Fn getgid +and +.Fn getegid +system calls are expected to conform to +.St -p1003.1-90 . +.Sh HISTORY +The +.Fn getgid +function appeared in +.At v4 . diff --git a/lib/libsys/getgroups.2 b/lib/libsys/getgroups.2 new file mode 100644 index 000000000000..91cca2748ec2 --- /dev/null +++ b/lib/libsys/getgroups.2 @@ -0,0 +1,104 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd January 21, 2011 +.Dt GETGROUPS 2 +.Os +.Sh NAME +.Nm getgroups +.Nd get group access list +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn getgroups "int gidsetlen" "gid_t *gidset" +.Sh DESCRIPTION +The +.Fn getgroups +system call +gets the current group access list of the user process +and stores it in the array +.Fa gidset . +The +.Fa gidsetlen +argument +indicates the number of entries that may be placed in +.Fa gidset . +The +.Fn getgroups +system call +returns the actual number of groups returned in +.Fa gidset . +At least one and as many as {NGROUPS_MAX}+1 values may be returned. +If +.Fa gidsetlen +is zero, +.Fn getgroups +returns the number of supplementary group IDs associated with +the calling process without modifying the array pointed to by +.Fa gidset . +.Pp +The value of +.Dv {NGROUPS_MAX} +should be obtained using +.Xr sysconf 3 +to avoid hard-coding it into the executable. +.Sh RETURN VALUES +A successful call returns the number of groups in the group set. +A value of -1 indicates that an error occurred, and the error +code is stored in the global variable +.Va errno . +.Sh ERRORS +The possible errors for +.Fn getgroups +are: +.Bl -tag -width Er +.It Bq Er EINVAL +The argument +.Fa gidsetlen +is smaller than the number of groups in the group set. +.It Bq Er EFAULT +The argument +.Fa gidset +specifies +an invalid address. +.El +.Sh SEE ALSO +.Xr setgroups 2 , +.Xr initgroups 3 , +.Xr sysconf 3 +.Sh STANDARDS +The +.Fn getgroups +system call conforms to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn getgroups +system call appeared in +.Bx 4.2 . diff --git a/lib/libsys/getitimer.2 b/lib/libsys/getitimer.2 new file mode 100644 index 000000000000..2d137d00d8c1 --- /dev/null +++ b/lib/libsys/getitimer.2 @@ -0,0 +1,192 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd May 1, 2020 +.Dt GETITIMER 2 +.Os +.Sh NAME +.Nm getitimer , +.Nm setitimer +.Nd get/set value of interval timer +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/time.h +.Fd "#define ITIMER_REAL 0" +.Fd "#define ITIMER_VIRTUAL 1" +.Fd "#define ITIMER_PROF 2" +.Ft int +.Fn getitimer "int which" "struct itimerval *value" +.Ft int +.Fn setitimer "int which" "const struct itimerval *value" "struct itimerval *ovalue" +.Sh DESCRIPTION +The system provides each process with three interval timers, +defined in +.In sys/time.h . +The +.Fn getitimer +system call returns the current value for the timer specified in +.Fa which +in the structure at +.Fa value . +The +.Fn setitimer +system call sets a timer to the specified +.Fa value +(returning the previous value of the timer if +.Fa ovalue +is not a null pointer). +.Pp +A timer value is defined by the +.Fa itimerval +structure: +.Bd -literal -offset indent +struct itimerval { + struct timeval it_interval; /* timer interval */ + struct timeval it_value; /* current value */ +}; +.Ed +.Pp +If +.Fa it_value +is non-zero, it indicates the time to the next timer expiration. +If +.Fa it_interval +is non-zero, it specifies a value to be used in reloading +.Fa it_value +when the timer expires. +Setting +.Fa it_value +to 0 disables a timer, regardless of the value of +.Fa it_interval . +Setting +.Fa it_interval +to 0 causes a timer to be disabled after its next expiration (assuming +.Fa it_value +is non-zero). +.Pp +Time values smaller than the resolution of the +system clock are rounded up to this resolution +(typically 10 milliseconds). +.Pp +The +.Dv ITIMER_REAL +timer decrements in real time. +A +.Dv SIGALRM +signal is +delivered when this timer expires. +.Pp +The +.Dv ITIMER_VIRTUAL +timer decrements in process virtual time. +It runs only when the process is executing. +A +.Dv SIGVTALRM +signal +is delivered when it expires. +.Pp +The +.Dv ITIMER_PROF +timer decrements both in process virtual time and +when the system is running on behalf of the process. +It is designed +to be used by interpreters in statistically profiling the execution +of interpreted programs. +Each time the +.Dv ITIMER_PROF +timer expires, the +.Dv SIGPROF +signal is +delivered. +Because this signal may interrupt in-progress +system calls, programs using this timer must be prepared to +restart interrupted system calls. +.Pp +The maximum number of seconds allowed for +.Fa it_interval +and +.Fa it_value +in +.Fn setitimer +is 100000000. +.Sh NOTES +Three macros for manipulating time values are defined in +.In sys/time.h . +The +.Fn timerclear +macro +sets a time value to zero, +.Fn timerisset +tests if a time value is non-zero, and +.Fn timercmp +compares two time values. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn getitimer +and +.Fn setitimer +system calls +will fail if: +.Bl -tag -width Er +.It Bq Er EFAULT +The +.Fa value +argument specified a bad address. +.It Bq Er EINVAL +The +.Fa value +argument specified a time that was too large +to be handled. +.El +.Sh SEE ALSO +.Xr gettimeofday 2 , +.Xr select 2 , +.Xr sigaction 2 , +.Xr clocks 7 +.Sh STANDARDS +The +.Fn getitimer +and +.Fn setitimer +functions conform to +.St -p1003.1-2001 . +The later +.St -p1003.1-2008 +revision however marked both functions as obsolescent, +recommending the use of +.Xr timer_gettime 2 +and +.Xr timer_settime 2 +instead. +.Sh HISTORY +The +.Fn getitimer +system call appeared in +.Bx 4.2 . diff --git a/lib/libsys/getlogin.2 b/lib/libsys/getlogin.2 new file mode 100644 index 000000000000..86583f6ae846 --- /dev/null +++ b/lib/libsys/getlogin.2 @@ -0,0 +1,201 @@ +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd September 9, 2020 +.Dt GETLOGIN 2 +.Os +.Sh NAME +.Nm getlogin , +.Nm getlogin_r , +.Nm setlogin +.Nd get/set login name +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft char * +.Fn getlogin void +.In sys/param.h +.Ft int +.Fn getlogin_r "char *name" "size_t len" +.Ft int +.Fn setlogin "const char *name" +.Sh DESCRIPTION +The +.Fn getlogin +routine +returns the login name of the user associated with the current session, +as previously set by +.Fn setlogin . +The name is normally associated with a login shell +at the time a session is created, +and is inherited by all processes descended from the login shell. +(This is true even if some of those processes assume another user ID, +for example when +.Xr su 1 +is used). +.Pp +The +.Fn getlogin_r +function +provides the same service as +.Fn getlogin +except the caller must provide the buffer +.Fa name +with length +.Fa len +bytes +to hold the result. +The buffer should be at least +.Dv MAXLOGNAME +bytes in length. +.Pp +The +.Fn setlogin +system call +sets the login name of the user associated with the current session to +.Fa name . +This system call is restricted to the super-user, and +is normally used only when a new session is being created on behalf +of the named user +(for example, at login time, or when a remote shell is invoked). +.Pp +.Em NOTE : +There is only one login name per session. +.Pp +It is +.Em CRITICALLY +important to ensure that +.Fn setlogin +is only ever called after the process has taken adequate steps to ensure +that it is detached from its parent's session. +Making a +.Fn setsid +system call is the +.Em ONLY +way to do this. +The +.Xr daemon 3 +function calls +.Fn setsid +which is an ideal way of detaching from a controlling terminal and +forking into the background. +.Pp +In particular, doing a +.Fn ioctl ttyfd TIOCNOTTY ...\& +or +.Fn setpgrp ...\& +is +.Em NOT +sufficient. +.Pp +Once a parent process does a +.Fn setsid +system call, it is acceptable for some child of that process to then do a +.Fn setlogin +even though it is not the session leader, but beware that ALL processes +in the session will change their login name at the same time, even the +parent. +.Pp +This is not the same as the traditional UNIX behavior of inheriting privilege. +.Pp +Since the +.Fn setlogin +system call is restricted to the super-user, it is assumed that (like +all other privileged programs) the programmer has taken adequate +precautions to prevent security violations. +.Sh RETURN VALUES +If a call to +.Fn getlogin +succeeds, it returns a pointer to a null-terminated string in a static buffer, +or +.Dv NULL +if the name has not been set. +The +.Fn getlogin_r +function +returns zero if successful, or the error number upon failure. +.Pp +.Rv -std setlogin +.Sh ERRORS +The following errors may be returned by these calls: +.Bl -tag -width Er +.It Bq Er EFAULT +The +.Fa name +argument gave an +invalid address. +.It Bq Er EINVAL +The +.Fa name +argument +pointed to a string that was too long. +Login names are limited to +.Dv MAXLOGNAME +(from +.In sys/param.h ) +characters, currently 33 including null. +.It Bq Er EPERM +The caller tried to set the login name and was not the super-user. +.It Bq Er ERANGE +The size of the buffer is smaller than the result to be returned. +.El +.Sh SEE ALSO +.Xr setsid 2 , +.Xr daemon 3 +.Sh STANDARDS +The +.Fn getlogin +system call +and +the +.Fn getlogin_r +function +conform to +.St -p1003.1-96 . +.Sh HISTORY +The +.Fn getlogin +system call first appeared in +.Bx 4.4 . +The return value of +.Fn getlogin_r +was changed from earlier versions of +.Fx +to be conformant with +.St -p1003.1-96 . +.Sh BUGS +In earlier versions of the system, +.Fn getlogin +failed unless the process was associated with a login terminal. +The current implementation (using +.Fn setlogin ) +allows getlogin to succeed even when the process has no controlling terminal. +In earlier versions of the system, the value returned by +.Fn getlogin +could not be trusted without checking the user ID. +Portable programs should probably still make this check. diff --git a/lib/libsys/getloginclass.2 b/lib/libsys/getloginclass.2 new file mode 100644 index 000000000000..e44428aeece5 --- /dev/null +++ b/lib/libsys/getloginclass.2 @@ -0,0 +1,97 @@ +.\"- +.\" Copyright (c) 2011 Edward Tomasz Napierala +.\" +.\" 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. +.\" +.Dd July 12, 2016 +.Dt GETLOGINCLASS 2 +.Os +.Sh NAME +.Nm getloginclass , +.Nm setloginclass +.Nd get/set login class +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn getloginclass "char *name" "size_t len" +.Ft int +.Fn setloginclass "const char *name" +.Sh DESCRIPTION +The +.Fn getloginclass +routine returns the login class name associated with the calling process, +as previously set by +.Fn setloginclass . +The caller must provide the buffer +.Fa name +with length +.Fa len +bytes to hold the result. +The buffer should be at least +.Dv MAXLOGNAME +bytes in length. +.Pp +The +.Fn setloginclass +system call sets the login class of the calling process to +.Fa name . +This system call is restricted to the super-user, and is normally used +only when a new session is being created on behalf of the named user +(for example, at login time, or when a remote shell is invoked). +Processes inherit login class from their parents. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The following errors may be returned by these calls: +.Bl -tag -width Er +.It Bq Er EFAULT +The +.Fa name +argument gave an invalid address. +.It Bq Er EINVAL +The +.Fa name +argument pointed to a string that was too long. +Login class names are limited to +.Dv MAXLOGNAME +(from +.In sys/param.h ) +characters, currently 33 including null. +.It Bq Er EPERM +The caller tried to set the login class and was not the super-user. +.It Bq Er ENAMETOOLONG +The size of the buffer is smaller than the result to be returned. +.El +.Sh SEE ALSO +.Xr ps 1 , +.Xr setusercontext 3 , +.Xr login.conf 5 , +.Xr rctl 8 +.Sh HISTORY +The +.Fn getloginclass +and +.Fn setloginclass +system calls first appeared in +.Fx 9.0 . diff --git a/lib/libsys/getpagesize.3 b/lib/libsys/getpagesize.3 new file mode 100644 index 000000000000..4828e654265b --- /dev/null +++ b/lib/libsys/getpagesize.3 @@ -0,0 +1,67 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd October 17, 2022 +.Dt GETPAGESIZE 3 +.Os +.Sh NAME +.Nm getpagesize +.Nd get system page size +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn getpagesize void +.Sh DESCRIPTION +The +.Fn getpagesize +function +returns the number of bytes in a page. +Page granularity is the granularity of many of the memory +management calls. +.Pp +The page size is a system +page size and may not be the same as the underlying +hardware page size. +.Pp +.St -p1003.1-2001 +removed +.Nm . +Portable applications should use +.Ql sysconf(_SC_PAGESIZE) +instead. +.Sh SEE ALSO +.Xr pagesize 1 , +.Xr sbrk 2 , +.Xr getpagesizes 3 , +.Xr sysconf 3 +.Sh HISTORY +The +.Fn getpagesize +function appeared in +.Bx 4.2 . diff --git a/lib/libsys/getpagesize.c b/lib/libsys/getpagesize.c new file mode 100644 index 000000000000..23d2c6ea5eda --- /dev/null +++ b/lib/libsys/getpagesize.c @@ -0,0 +1,51 @@ +/*- + * SPDX-License-Identifier: BSD-3-Clause + * + * Copyright (c) 1989, 1993 + * The Regents of the University of California. All rights reserved. + * + * 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. + * 3. Neither the name of the University nor the names of its contributors + * may be used to endorse or promote products derived from this software + * without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. + */ + +#include <sys/param.h> +#include <sys/auxv.h> + +#include "libc_private.h" + +/* + * NB: This function may be called from malloc(3) at initialization + * NB: so must not result in a malloc(3) related call! + */ + +int +getpagesize(void) +{ + int value; + + if (_elf_aux_info(AT_PAGESZ, &value, sizeof(value)) != 0) + value = PAGE_SIZE; + + return (value); +} diff --git a/lib/libsys/getpagesizes.3 b/lib/libsys/getpagesizes.3 new file mode 100644 index 000000000000..e00a1be7c550 --- /dev/null +++ b/lib/libsys/getpagesizes.3 @@ -0,0 +1,97 @@ +.\" Copyright (c) 2009 Alan L. Cox <alc@cs.rice.edu> +.\" All rights reserved. +.\" +.\" 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. +.\" +.Dd September 21, 2009 +.Dt GETPAGESIZES 3 +.Os +.Sh NAME +.Nm getpagesizes +.Nd "get system page sizes" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/mman.h +.Ft int +.Fn getpagesizes "size_t pagesize[]" "int nelem" +.Sh DESCRIPTION +The +.Fn getpagesizes +function retrieves page size information from the system. +When it is called with +.Fa pagesize +specified as +.Dv NULL +and +.Fa nelem +specified as 0, it returns the number of distinct page sizes that are +supported by the system. +Otherwise, it assigns up to +.Fa nelem +of the system-supported page sizes to consecutive elements of the +array referenced by +.Fa pagesize . +These page sizes are expressed in bytes. +In this case, +.Fn getpagesizes +returns the number of such page sizes that it assigned to the array. +.Sh RETURN VALUES +If successful, the +.Fn getpagesizes +function returns either the number of page sizes that are supported by +the system or the number of supported page sizes that it assigned to +the array referenced by +.Fa pagesize . +Otherwise, it returns the value\~\-1 and sets +.Va errno +to indicate the error. +.Sh ERRORS +The +.Fn getpagesizes +function will succeed unless: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa pagesize +argument is +.Dv NULL +and the +.Fa nelem +argument is non-zero. +.It Bq Er EINVAL +The +.Fa nelem +argument is less than zero. +.El +.Sh SEE ALSO +.Xr getpagesize 3 +.Sh HISTORY +The +.Fn getpagesizes +function first appeared in Solaris 9. +This manual page was written in conjunction with a new but compatible +implementation that was first released in +.Fx 7.3 . +.Sh AUTHORS +This manual page was written by +.An Alan L. Cox Aq Mt alc@cs.rice.edu . diff --git a/lib/libsys/getpagesizes.c b/lib/libsys/getpagesizes.c new file mode 100644 index 000000000000..7f481f84177a --- /dev/null +++ b/lib/libsys/getpagesizes.c @@ -0,0 +1,75 @@ +/*- + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (c) 2009 Alan L. Cox <alc@cs.rice.edu> + * All rights reserved. + * + * 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. + */ + +#include <sys/param.h> +#include <sys/auxv.h> +#include <sys/errno.h> + +#include "libc_private.h" + +/* + * Retrieves page size information from the system. Specifically, returns the + * number of distinct page sizes that are supported by the system, if + * "pagesize" is NULL and "nelem" is 0. Otherwise, assigns up to "nelem" of + * the system-supported page sizes to consecutive elements of the array + * referenced by "pagesize", and returns the number of such page sizes that it + * assigned to the array. These page sizes are expressed in bytes. + * + * The implementation of this function does not directly or indirectly call + * malloc(3) or any other dynamic memory allocator that may itself call this + * function. + */ +int +getpagesizes(size_t pagesize[], int nelem) +{ + static u_long ps[MAXPAGESIZES]; + static int nops; + int i; + + if (nelem < 0 || (nelem > 0 && pagesize == NULL)) { + errno = EINVAL; + return (-1); + } + /* Cache the result */ + if (nops == 0) { + if (_elf_aux_info(AT_PAGESIZES, ps, sizeof(ps)) != 0) + ps[0] = PAGE_SIZE; + /* Count the number of page sizes that are supported. */ + nops = nitems(ps); + while (nops > 0 && ps[nops - 1] == 0) + nops--; + } + if (pagesize == NULL) + return (nops); + /* Return up to "nelem" page sizes from the cached result. */ + if (nelem > nops) + nelem = nops; + for (i = 0; i < nelem; i++) + pagesize[i] = ps[i]; + return (nelem); +} diff --git a/lib/libsys/getpeername.2 b/lib/libsys/getpeername.2 new file mode 100644 index 000000000000..983436dd3230 --- /dev/null +++ b/lib/libsys/getpeername.2 @@ -0,0 +1,95 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd June 4, 1993 +.Dt GETPEERNAME 2 +.Os +.Sh NAME +.Nm getpeername +.Nd get name of connected peer +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.Ft int +.Fn getpeername "int s" "struct sockaddr * restrict name" "socklen_t * restrict namelen" +.Sh DESCRIPTION +The +.Fn getpeername +system call +returns the name of the peer connected to +socket +.Fa s . +The +.Fa namelen +argument should be initialized to indicate +the amount of space pointed to by +.Fa name . +On return it contains the actual size of the name +returned (in bytes). +The name is truncated if the buffer provided is too small. +.Sh RETURN VALUES +.Rv -std getpeername +.Sh ERRORS +The call succeeds unless: +.Bl -tag -width Er +.It Bq Er EBADF +The argument +.Fa s +is not a valid descriptor. +.It Bq Er ECONNRESET +The connection has been reset by the peer. +.It Bq Er EINVAL +The value of the +.Fa namelen +argument is not valid. +.It Bq Er ENOTSOCK +The argument +.Fa s +is a file, not a socket. +.It Bq Er ENOTCONN +The socket is not connected. +.It Bq Er ENOBUFS +Insufficient resources were available in the system +to perform the operation. +.It Bq Er EFAULT +The +.Fa name +argument points to memory not in a valid part of the +process address space. +.El +.Sh SEE ALSO +.Xr accept 2 , +.Xr bind 2 , +.Xr getsockname 2 , +.Xr socket 2 +.Sh HISTORY +The +.Fn getpeername +system call appeared in +.Bx 4.2 . diff --git a/lib/libsys/getpgrp.2 b/lib/libsys/getpgrp.2 new file mode 100644 index 000000000000..3b69d8486941 --- /dev/null +++ b/lib/libsys/getpgrp.2 @@ -0,0 +1,139 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd June 4, 1993 +.Dt GETPGRP 2 +.Os +.Sh NAME +.Nm getpgrp +.Nd get process group +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft pid_t +.Fn getpgrp void +.Ft pid_t +.Fn getpgid "pid_t pid" +.Sh DESCRIPTION +The process group of the current process is returned by +.Fn getpgrp . +The process group of the process identified by +.Fa pid +is returned by +.Fn getpgid . +If +.Fa pid +is zero, +.Fn getpgid +returns the process group of the current process. +.Pp +Process groups are used for distribution of signals, and +by terminals to arbitrate requests for their input: processes +that have the same process group as the terminal are foreground +and may read, while others will block with a signal if they attempt +to read. +.Pp +This system call is thus used by programs such as +.Xr csh 1 +to create +process groups +in implementing job control. +The +.Fn tcgetpgrp +and +.Fn tcsetpgrp +calls +are used to get/set the process group of the control terminal. +.Sh RETURN VALUES +The +.Fn getpgrp +system call always succeeds. +Upon successful completion, the +.Fn getpgid +system call returns the process group of the specified process; +otherwise, it returns a value of \-1 and sets +.Va errno +to indicate the error. +.Sh COMPATIBILITY +This version of +.Fn getpgrp +differs from past Berkeley versions by not taking a +.Fa "pid_t pid" +argument. +This incompatibility is required by +.St -p1003.1-90 . +.Pp +From the +.St -p1003.1-90 +Rationale: +.Pp +.Bx 4.3 +provides a +.Fn getpgrp +system call that returns the process group ID for a specified process. +Although this function is used to support job control, all known +job-control shells always specify the calling process with this +function. +Thus, the simpler +.At V +.Fn getpgrp +suffices, and the added complexity of the +.Bx 4.3 +.Fn getpgrp +has been omitted from POSIX.1. +The old functionality is available from the +.Fn getpgid +system call. +.Sh ERRORS +The +.Fn getpgid +system call +will succeed unless: +.Bl -tag -width Er +.It Bq Er ESRCH +there is no process whose process ID equals +.Fa pid +.El +.Sh SEE ALSO +.Xr getsid 2 , +.Xr setpgid 2 , +.Xr termios 4 +.Sh STANDARDS +The +.Fn getpgrp +system call is expected to conform to +.St -p1003.1-90 . +.Sh HISTORY +The +.Fn getpgrp +system call appeared in +.Bx 4.0 . +The +.Fn getpgid +system call is derived from its usage in +.At V.4 . diff --git a/lib/libsys/getpid.2 b/lib/libsys/getpid.2 new file mode 100644 index 000000000000..4dc1940091e7 --- /dev/null +++ b/lib/libsys/getpid.2 @@ -0,0 +1,87 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd December 15, 2015 +.Dt GETPID 2 +.Os +.Sh NAME +.Nm getpid , +.Nm getppid +.Nd get parent or calling process identification +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft pid_t +.Fn getpid void +.Ft pid_t +.Fn getppid void +.Sh DESCRIPTION +The +.Fn getpid +system call +returns +the process ID of +the calling process. +Though the ID is guaranteed to be unique, it should +.Em NOT +be used for constructing temporary file names, for +security reasons; see +.Xr mkstemp 3 +instead. +.Pp +The +.Fn getppid +system call +returns the process ID of the parent +of the calling process. +.Sh ERRORS +The +.Fn getpid +and +.Fn getppid +system calls are always successful, and no return value is reserved to +indicate an error. +.Sh SEE ALSO +.Xr fork 2 , +.Xr getpgrp 2 , +.Xr kill 2 , +.Xr setpgid 2 , +.Xr setsid 2 , +.Xr exec 3 +.Sh STANDARDS +The +.Fn getpid +and +.Fn getppid +system calls are expected to conform to +.St -p1003.1-90 . +.Sh HISTORY +The +.Fn getpid +function appeared in +.At v7 . diff --git a/lib/libsys/getpriority.2 b/lib/libsys/getpriority.2 new file mode 100644 index 000000000000..a044f1c628c8 --- /dev/null +++ b/lib/libsys/getpriority.2 @@ -0,0 +1,147 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd June 4, 1993 +.Dt GETPRIORITY 2 +.Os +.Sh NAME +.Nm getpriority , +.Nm setpriority +.Nd get/set program scheduling priority +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/time.h +.In sys/resource.h +.Ft int +.Fn getpriority "int which" "int who" +.Ft int +.Fn setpriority "int which" "int who" "int prio" +.Sh DESCRIPTION +The scheduling +priority of the process, process group, or user, as indicated by +.Fa which +and +.Fa who +is obtained with the +.Fn getpriority +system call and set with the +.Fn setpriority +system call. +The +.Fa which +argument +is one of +.Dv PRIO_PROCESS , +.Dv PRIO_PGRP , +or +.Dv PRIO_USER , +and +.Fa who +is interpreted relative to +.Fa which +(a process identifier for +.Dv PRIO_PROCESS , +process group +identifier for +.Dv PRIO_PGRP , +and a user ID for +.Dv PRIO_USER ) . +A zero value of +.Fa who +denotes the current process, process group, or user. +The +.Fa prio +argument +is a value in the range -20 to 20. +The default priority is 0; +lower priorities cause more favorable scheduling. +.Pp +The +.Fn getpriority +system call returns the highest priority (lowest numerical value) +enjoyed by any of the specified processes. +The +.Fn setpriority +system call sets the priorities of all of the specified processes +to the specified value. +Only the super-user may lower priorities. +.Sh RETURN VALUES +Since +.Fn getpriority +can legitimately return the value -1, it is necessary +to clear the external variable +.Va errno +prior to the +call, then check it afterward to determine +if a -1 is an error or a legitimate value. +.Pp +.Rv -std setpriority +.Sh ERRORS +The +.Fn getpriority +and +.Fn setpriority +system calls +will fail if: +.Bl -tag -width Er +.It Bq Er ESRCH +No process was located using the +.Fa which +and +.Fa who +values specified. +.It Bq Er EINVAL +The +.Fa which +argument +was not one of +.Dv PRIO_PROCESS , +.Dv PRIO_PGRP , +or +.Dv PRIO_USER . +.El +.Pp +In addition to the errors indicated above, +.Fn setpriority +will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +A process was located, but neither its effective nor real user +ID matched the effective user ID of the caller. +.It Bq Er EACCES +A non super-user attempted to lower a process priority. +.El +.Sh SEE ALSO +.Xr nice 1 , +.Xr fork 2 , +.Xr renice 8 +.Sh HISTORY +The +.Fn getpriority +system call appeared in +.Bx 4.2 . diff --git a/lib/libsys/getrandom.2 b/lib/libsys/getrandom.2 new file mode 100644 index 000000000000..37b5ce7d22be --- /dev/null +++ b/lib/libsys/getrandom.2 @@ -0,0 +1,131 @@ +.\" Copyright 2020, 2018 Conrad Meyer <cem@FreeBSD.org>. All rights reserved. +.\" +.\" 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 AUTHORS 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 AUTHORS 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. +.\" +.Dd January 12, 2020 +.Dt GETRANDOM 2 +.Os +.Sh NAME +.Nm getrandom +.Nd get random data +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/random.h +.Ft ssize_t +.Fn getrandom "void *buf" "size_t buflen" "unsigned int flags" +.Sh DESCRIPTION +.Fn getrandom +fills +.Fa buf +with up to +.Fa buflen +bytes of random data. +.Pp +The +.Fa flags +argument may include zero or more of the following: +.Bl -tag -width _GRND_NONBLOCK_ +.It Ql GRND_NONBLOCK +Return +.Er EAGAIN +instead of blocking, if the +.Xr random 4 +device has not yet been seeded. +By default, +.Fn getrandom +will block until the device is seeded. +.It Ql GRND_RANDOM +This flag does nothing on +.Fx . +.Pa /dev/random +and +.Pa /dev/urandom +are identical. +.It Ql GRND_INSECURE +This flag is treated as an alternative name for +.Dv GRND_NONBLOCK . +It is provided solely for API compatibility with Linux. +.El +.Pp +If the +.Xr random 4 +device has been seeded, reads of up to 256 bytes will always return as many +bytes as requested and will not be interrupted by signals. +.Sh RETURN VALUES +Upon successful completion, the number of bytes which were actually read is +returned. +For requests larger than 256 bytes, this can be fewer bytes than were +requested. +Otherwise, -1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn getrandom +operation returns the following errors: +.Bl -tag -width Er +.It Bq Er EAGAIN +The +.Ql GRND_NONBLOCK +(or +.Ql GRND_INSECURE ) +flag was set and the +.Xr random 4 +device was not yet seeded. +.It Bq Er EFAULT +The +.Fa buf +parameter points to an invalid address. +.It Bq Er EINTR +The sleep was interrupted by a signal. +.It Bq Er EINVAL +An invalid +.Fa flags +was specified. +.It Bq Er EINVAL +The requested +.Fa buflen +was larger than +.Dv IOSIZE_MAX . +.El +.Sh SEE ALSO +.Xr arc4random 3 , +.Xr getentropy 3 , +.Xr random 4 +.Sh STANDARDS +.Fn getrandom +is non-standard. +It is present in Linux. +.Sh HISTORY +The +.Fn getrandom +system call first appeared in +.Fx 12.0 . +.Sh CAVEATS +Unlike Linux, the +.Dv GRND_INSECURE +flag on +.Fx +does not produce any output before the +.Xr random 4 +device is seeded. diff --git a/lib/libsys/getrlimit.2 b/lib/libsys/getrlimit.2 new file mode 100644 index 000000000000..d54dc703ada0 --- /dev/null +++ b/lib/libsys/getrlimit.2 @@ -0,0 +1,242 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd July 25, 2024 +.Dt GETRLIMIT 2 +.Os +.Sh NAME +.Nm getrlimit , +.Nm setrlimit +.Nd control maximum system resource consumption +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/time.h +.In sys/resource.h +.Ft int +.Fn getrlimit "int resource" "struct rlimit *rlp" +.Ft int +.Fn setrlimit "int resource" "const struct rlimit *rlp" +.Sh DESCRIPTION +Limits on the consumption of system resources by the current process +and each process it creates may be obtained with the +.Fn getrlimit +system call, and set with the +.Fn setrlimit +system call. +.Pp +The +.Fa resource +argument is one of the following: +.Bl -tag -width RLIMIT_FSIZEAA +.It Dv RLIMIT_AS +The maximum amount (in bytes) of virtual memory the process is +allowed to map. +.It Dv RLIMIT_CORE +The largest size (in bytes) +.Xr core 5 +file that may be created. +.It Dv RLIMIT_CPU +The maximum amount of cpu time (in seconds) to be used by +each process. +.It Dv RLIMIT_DATA +The maximum size (in bytes) of the data segment for a process; +this defines how far a program may extend its break with the +.Xr sbrk 2 +function. +.It Dv RLIMIT_FSIZE +The largest size (in bytes) file that may be created. +.It Dv RLIMIT_KQUEUES +The maximum number of kqueues this user id is allowed to create. +.It Dv RLIMIT_MEMLOCK +The maximum size (in bytes) which a process may lock into memory +using the +.Xr mlock 2 +system call. +.It Dv RLIMIT_NOFILE +The maximum number of open files for this process. +.It Dv RLIMIT_NPROC +The maximum number of simultaneous processes for this user id. +.It Dv RLIMIT_NPTS +The maximum number of pseudo-terminals this user id is allowed to create. +.It Dv RLIMIT_PIPEBUF +The maximum total size of in-kernel buffers for bi-directional pipes/fifos +that this user id is allowed to consume. +The buffers for kernel FIFOs created on the first open of a filesystem +object created by +.Pq Xr mkfifo 2 +are also charged to the user ID of the process opening it, +not the FIFO's filesystem owner. +Despite somewhat unexpected, this is in fact fair, since user of the fifo +is not necessary its creator. +.It Dv RLIMIT_RSS +When there is memory pressure and swap is available, prioritize eviction of +a process' resident pages beyond this amount (in bytes). +When memory is not under pressure, this rlimit is effectively ignored. +.Pp +Processes that exceed their set +.Dv RLIMIT_RSS +are not signalled or halted. +The limit is merely a hint to the VM daemon to prefer to deactivate pages from +processes that have exceeded their set +.Dv RLIMIT_RSS . +.It Dv RLIMIT_SBSIZE +The maximum size (in bytes) of socket buffer usage for this user. +This limits the amount of network memory, and hence the amount of +mbufs, that this user may hold at any time. +.It Dv RLIMIT_STACK +The maximum size (in bytes) of the stack segment for a process; +this defines how far a program's stack segment may be extended. +Stack extension is performed automatically by the system. +.It Dv RLIMIT_SWAP +The maximum size (in bytes) of the swap space that may be reserved or +used by all of this user id's processes. +This limit is enforced only if bit 1 of the +.Va vm.overcommit +sysctl is set. +Please see +.Xr tuning 7 +for a complete description of this sysctl. +.It Dv RLIMIT_UMTXP +The limit of the number of process-shared posix thread library objects +allocated by user id. +.It Dv RLIMIT_VMEM +An alias for +.Dv RLIMIT_AS . +.El +.Pp +A resource limit is specified as a soft limit and a hard limit. +When a soft limit is exceeded, a process might or might not receive a signal. +For example, signals are generated when the cpu time or file size is exceeded, +but not if the address space or RSS limit is exceeded. +A program that exceeds the soft limit is allowed to continue execution until it +reaches the hard limit, or modifies its own resource limit. +Even reaching the hard limit does not necessarily halt a process. +For example, if the RSS hard limit is exceeded, nothing happens. +.Pp +The +.Vt rlimit +structure is used to specify the hard and soft limits on a resource. +.Bd -literal -offset indent +struct rlimit { + rlim_t rlim_cur; /* current (soft) limit */ + rlim_t rlim_max; /* maximum value for rlim_cur */ +}; +.Ed +.Pp +Only the super-user may raise the maximum limits. +Other users +may only alter +.Fa rlim_cur +within the range from 0 to +.Fa rlim_max +or (irreversibly) lower +.Fa rlim_max . +.Pp +An +.Dq infinite +value for a limit is defined as +.Dv RLIM_INFINITY . +.Pp +Because this information is stored in the per-process information, +this system call must be executed directly by the shell if it +is to affect all future processes created by the shell; +.Ic limit +is thus a built-in command to +.Xr csh 1 . +.Pp +The system refuses to extend the data or stack space when the limits +would be exceeded in the normal way: a +.Xr brk 2 +function fails if the data space limit is reached. +When the stack limit is reached, the process receives +a segmentation fault +.Pq Dv SIGSEGV ; +if this signal is not +caught by a handler using the signal stack, this signal +will kill the process. +.Pp +A file I/O operation that would create a file larger that the process' +soft limit will cause the write to fail and a signal +.Dv SIGXFSZ +to be +generated; this normally terminates the process, but may be caught. +When +the soft cpu time limit is exceeded, a +.Dv SIGXCPU +signal is sent to the +offending process. +.Pp +When most operations would allocate more virtual memory than allowed by the +soft limit of +.Dv RLIMIT_AS , +the operation fails with +.Dv ENOMEM +and no signal is raised. +A notable exception is stack extension, described above. +If stack extension would allocate more virtual memory than allowed by the soft +limit of +.Dv RLIMIT_AS , +a +.Dv SIGSEGV +signal will be delivered. +The caller is free to raise the soft address space limit up to the hard limit +and retry the allocation. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn getrlimit +and +.Fn setrlimit +system calls +will fail if: +.Bl -tag -width Er +.It Bq Er EFAULT +The address specified for +.Fa rlp +is invalid. +.It Bq Er EPERM +The limit specified to +.Fn setrlimit +would have +raised the maximum limit value, and the caller is not the super-user. +.El +.Sh SEE ALSO +.Xr csh 1 , +.Xr quota 1 , +.Xr quotactl 2 , +.Xr sigaction 2 , +.Xr sigaltstack 2 , +.Xr sysctl 3 , +.Xr ulimit 3 +.Sh HISTORY +The +.Fn getrlimit +system call appeared in +.Bx 4.2 . diff --git a/lib/libsys/getrlimitusage.2 b/lib/libsys/getrlimitusage.2 new file mode 100644 index 000000000000..e2114def56c2 --- /dev/null +++ b/lib/libsys/getrlimitusage.2 @@ -0,0 +1,100 @@ +.\" Copyright (c) 2024 The FreeBSD Foundation +.\" +.\" This documentation was written by +.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" 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 AUTHORS 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 AUTHORS 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. +.\" +.Dd September 27, 2024 +.Dt GETRLIMITUSAGE 2 +.Os +.Sh NAME +.Nm getrlimitusage +.Nd Query usage of the current process' limited resources +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/resource.h +.Ft int +.Fn getrlimitusage "unsigned which" "int flags" "rlim_t *res" +.Sh DESCRIPTION +The +.Nm +system call allows the process to query current consumption of the resources +limited by the +.Xr setrlimit 2 +call. +.Pp +The +.Fa which +argument specifies the resource, same as for +.Xr getrlimit 2 +and +.Xr setrlimit 2 +calls, see their man page for the list of enforced resource types. +.Pp +The +.Fa flags +argument modifies the behavior of the call in the following ways: +.Bl -tag -width GETRLIMITUSAGE_XXXXXX +.It Va GETRLIMITUSAGE_EUID +Query the resource usage for user identified by effective UID of the process, +instead of the real UID (which is default for accounting). +.El +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn getrlimitusage +system call will fail if: +.Bl -tag -width Er +.It Bq Er EFAULT +The address specified for +.Fa res +is invalid. +.It Bq Er EINVAL +The resource specified to +.Fn getrlimitusage +in the +.Fa which +argument is unknown. +.It Bq Er ENXIO +The resource specified to +.Fn getrlimitusage +in the +.Fa which +argument is not accounted, but only enforced in specific situations. +Examples of such resources are +.Va RLIMIT_FSIZE +and +.Va RLIMIT_CORE . +.El +.Sh SEE ALSO +.Xr procstat 1 , +.Xr getrlimit 2 , +.Xr setrlimit 2 +.Sh HISTORY +The +.Fn getrlimitusage +system call appeared in +.Bx 15.0 . diff --git a/lib/libsys/getrusage.2 b/lib/libsys/getrusage.2 new file mode 100644 index 000000000000..f47960db0c6a --- /dev/null +++ b/lib/libsys/getrusage.2 @@ -0,0 +1,183 @@ +.\" Copyright (c) 1985, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd May 1, 2010 +.Dt GETRUSAGE 2 +.Os +.Sh NAME +.Nm getrusage +.Nd get information about resource utilization +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/time.h +.In sys/resource.h +.Fd "#define RUSAGE_SELF 0" +.Fd "#define RUSAGE_CHILDREN -1" +.Fd "#define RUSAGE_THREAD 1" +.Ft int +.Fn getrusage "int who" "struct rusage *rusage" +.Sh DESCRIPTION +The +.Fn getrusage +system call +returns information describing the resources utilized by the current +thread, the current process, or all its terminated child processes. +The +.Fa who +argument is either +.Dv RUSAGE_THREAD , +.Dv RUSAGE_SELF , +or +.Dv RUSAGE_CHILDREN . +The buffer to which +.Fa rusage +points will be filled in with +the following structure: +.Bd -literal +struct rusage { + struct timeval ru_utime; /* user time used */ + struct timeval ru_stime; /* system time used */ + long ru_maxrss; /* max resident set size */ + long ru_ixrss; /* integral shared text memory size */ + long ru_idrss; /* integral unshared data size */ + long ru_isrss; /* integral unshared stack size */ + long ru_minflt; /* page reclaims */ + long ru_majflt; /* page faults */ + long ru_nswap; /* swaps */ + long ru_inblock; /* block input operations */ + long ru_oublock; /* block output operations */ + long ru_msgsnd; /* messages sent */ + long ru_msgrcv; /* messages received */ + long ru_nsignals; /* signals received */ + long ru_nvcsw; /* voluntary context switches */ + long ru_nivcsw; /* involuntary context switches */ +}; +.Ed +.Pp +The fields are interpreted as follows: +.Bl -tag -width ru_minfltaa +.It Fa ru_utime +the total amount of time spent executing in user mode. +.It Fa ru_stime +the total amount of time spent in the system executing on behalf +of the process(es). +.It Fa ru_maxrss +the maximum resident set size utilized (in kilobytes). +.It Fa ru_ixrss +an +.Dq integral +value indicating the amount of memory used +by the text segment +that was also shared among other processes. +This value is expressed +in units of kilobytes * ticks-of-execution. +Ticks are statistics clock ticks. +The statistics clock has a frequency of +.Fn sysconf _SC_CLK_TCK +ticks per second. +.It Fa ru_idrss +an integral value of the amount of unshared memory residing in the +data segment of a process (expressed in units of +kilobytes * ticks-of-execution). +.It Fa ru_isrss +an integral value of the amount of unshared memory residing in the +stack segment of a process (expressed in units of +kilobytes * ticks-of-execution). +.It Fa ru_minflt +the number of page faults serviced without any I/O activity; here +I/O activity is avoided by +.Dq reclaiming +a page frame from +the list of pages awaiting reallocation. +.It Fa ru_majflt +the number of page faults serviced that required I/O activity. +.It Fa ru_nswap +the number of times a process was +.Dq swapped +out of main +memory. +.It Fa ru_inblock +the number of times the file system had to perform input. +.It Fa ru_oublock +the number of times the file system had to perform output. +.It Fa ru_msgsnd +the number of IPC messages sent. +.It Fa ru_msgrcv +the number of IPC messages received. +.It Fa ru_nsignals +the number of signals delivered. +.It Fa ru_nvcsw +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). +.It Fa ru_nivcsw +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. +.El +.Sh NOTES +The numbers +.Fa ru_inblock +and +.Fa ru_oublock +account only for real +I/O; data supplied by the caching mechanism is charged only +to the first process to read or write the data. +.Sh RETURN VALUES +.Rv -std getrusage +.Sh ERRORS +The +.Fn getrusage +system call will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa who +argument is not a valid value. +.It Bq Er EFAULT +The address specified by the +.Fa rusage +argument is not in a valid part of the process address space. +.El +.Sh SEE ALSO +.Xr gettimeofday 2 , +.Xr wait 2 , +.Xr clocks 7 +.Sh HISTORY +The +.Fn getrusage +system call appeared in +.Bx 4.2 . +The +.Dv RUSAGE_THREAD +facility first appeared in +.Fx 8.1 . +.Sh BUGS +There is no way to obtain information about a child process +that has not yet terminated. diff --git a/lib/libsys/getsid.2 b/lib/libsys/getsid.2 new file mode 100644 index 000000000000..ad7dbb887a08 --- /dev/null +++ b/lib/libsys/getsid.2 @@ -0,0 +1,80 @@ +.\" Copyright (c) 1997 Peter Wemm <peter@FreeBSD.org> +.\" +.\" 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. +.\" +.Dd August 19, 1997 +.Dt GETSID 2 +.Os +.Sh NAME +.Nm getsid +.Nd get process session +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft pid_t +.Fn getsid "pid_t pid" +.Sh DESCRIPTION +The session ID of the process identified by +.Fa pid +is returned by +.Fn getsid . +If +.Fa pid +is zero, +.Fn getsid +returns the session ID of the current process. +.Sh RETURN VALUES +Upon successful completion, the +.Fn getsid +system call +returns the session ID of +the specified process; otherwise, it returns a value of -1 and +sets errno to indicate an error. +.Sh ERRORS +The +.Fn getsid +system call +will succeed unless: +.Bl -tag -width Er +.It Bq Er ESRCH +if there is no process with a process ID equal to +.Fa pid . +.El +.Pp +Note that an implementation may restrict this system call to +processes within the same session ID as the calling process. +.Sh SEE ALSO +.Xr getpgid 2 , +.Xr getpgrp 2 , +.Xr setpgid 2 , +.Xr setsid 2 , +.Xr termios 4 +.Sh HISTORY +The +.Fn getsid +system call appeared in +.Fx 3.0 . +The +.Fn getsid +system call is derived from its usage in +.At V . diff --git a/lib/libsys/getsockname.2 b/lib/libsys/getsockname.2 new file mode 100644 index 000000000000..bee672695812 --- /dev/null +++ b/lib/libsys/getsockname.2 @@ -0,0 +1,95 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd June 4, 1993 +.Dt GETSOCKNAME 2 +.Os +.Sh NAME +.Nm getsockname +.Nd get socket name +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.Ft int +.Fn getsockname "int s" "struct sockaddr * restrict name" "socklen_t * restrict namelen" +.Sh DESCRIPTION +The +.Fn getsockname +system call +returns the current +.Fa name +for the specified socket. +The +.Fa namelen +argument should be initialized to indicate +the amount of space pointed to by +.Fa name . +On return it contains the actual size of the name +returned (in bytes). +.Sh RETURN VALUES +.Rv -std getsockname +.Sh ERRORS +The call succeeds unless: +.Bl -tag -width Er +.It Bq Er EBADF +The argument +.Fa s +is not a valid descriptor. +.It Bq Er ECONNRESET +The connection has been reset by the peer. +.It Bq Er EINVAL +The value of the +.Fa namelen +argument is not valid. +.It Bq Er ENOTSOCK +The argument +.Fa s +is a file, not a socket. +.It Bq Er ENOBUFS +Insufficient resources were available in the system +to perform the operation. +.It Bq Er EFAULT +The +.Fa name +argument points to memory not in a valid part of the +process address space. +.El +.Sh SEE ALSO +.Xr bind 2 , +.Xr getpeername 2 , +.Xr socket 2 +.Sh HISTORY +The +.Fn getsockname +system call appeared in +.Bx 4.2 . +.Sh BUGS +Names bound to sockets in the UNIX domain are inaccessible; +.Fn getsockname +returns a zero length name. diff --git a/lib/libsys/getsockopt.2 b/lib/libsys/getsockopt.2 new file mode 100644 index 000000000000..3867824681d7 --- /dev/null +++ b/lib/libsys/getsockopt.2 @@ -0,0 +1,696 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd November 25, 2024 +.Dt GETSOCKOPT 2 +.Os +.Sh NAME +.Nm getsockopt , +.Nm setsockopt +.Nd get and set options on sockets +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.Ft int +.Fn getsockopt "int s" "int level" "int optname" "void * restrict optval" "socklen_t * restrict optlen" +.Ft int +.Fn setsockopt "int s" "int level" "int optname" "const void *optval" "socklen_t optlen" +.Sh DESCRIPTION +The +.Fn getsockopt +and +.Fn setsockopt +system calls +manipulate the +.Em options +associated with a socket. +Options may exist at multiple +protocol levels; they are always present at the uppermost +.Dq socket +level. +.Pp +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 socket level, +.Fa level +is specified as +.Dv 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 +.Tn TCP +protocol, +.Fa level +should be set to the protocol number of +.Tn TCP ; +see +.Xr getprotoent 3 . +.Pp +The +.Fa optval +and +.Fa optlen +arguments +are used to access option values for +.Fn setsockopt . +For +.Fn getsockopt +they identify a buffer in which the value for the +requested option(s) are to be returned. +For +.Fn getsockopt , +.Fa optlen +is a value-result argument, initially containing the +size of the buffer pointed to by +.Fa optval , +and modified on return to indicate the actual size of +the value returned. +If no option value is +to be supplied or returned, +.Fa optval +may be NULL. +.Pp +The +.Fa optname +argument +and any specified options are passed uninterpreted to the appropriate +protocol module for interpretation. +The include file +.In sys/socket.h +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. +.Pp +Most socket-level options utilize an +.Vt int +argument for +.Fa optval . +For +.Fn setsockopt , +the argument should be non-zero to enable a boolean option, +or zero if the option is to be disabled. +.Dv SO_LINGER +uses a +.Vt "struct linger" +argument, defined in +.In sys/socket.h , +which specifies the desired state of the option and the +linger interval (see below). +.Dv SO_SNDTIMEO +and +.Dv SO_RCVTIMEO +use a +.Vt "struct timeval" +argument, defined in +.In sys/time.h . +.Pp +The following options are recognized at the socket level. +For protocol-specific options, see protocol manual pages, +e.g. +.Xr ip 4 +or +.Xr tcp 4 . +Except as noted, each may be examined with +.Fn getsockopt +and set with +.Fn setsockopt . +.Bl -column SO_ACCEPTFILTER -offset indent +.It Dv SO_DEBUG Ta "enables recording of debugging information" +.It Dv SO_REUSEADDR Ta "enables local address reuse" +.It Dv SO_REUSEPORT Ta "enables duplicate address and port bindings" +.It Dv SO_REUSEPORT_LB Ta "enables duplicate address and port bindings with load balancing" +.It Dv SO_KEEPALIVE Ta "enables keep connections alive" +.It Dv SO_DONTROUTE Ta "enables routing bypass for outgoing messages" +.It Dv SO_LINGER Ta "linger on close if data present" +.It Dv SO_BROADCAST Ta "enables permission to transmit broadcast messages" +.It Dv SO_OOBINLINE Ta "enables reception of out-of-band data in band" +.It Dv SO_SNDBUF Ta "set buffer size for output" +.It Dv SO_RCVBUF Ta "set buffer size for input" +.It Dv SO_SNDLOWAT Ta "set minimum count for output" +.It Dv SO_RCVLOWAT Ta "set minimum count for input" +.It Dv SO_SNDTIMEO Ta "set timeout value for output" +.It Dv SO_RCVTIMEO Ta "set timeout value for input" +.It Dv SO_ACCEPTFILTER Ta "set accept filter on listening socket" +.It Dv SO_NOSIGPIPE Ta +controls generation of +.Dv SIGPIPE +for the socket +.It Dv SO_TIMESTAMP Ta "enables reception of a timestamp with datagrams" +.It Dv SO_BINTIME Ta "enables reception of a timestamp with datagrams" +.It Dv SO_ACCEPTCONN Ta "get listening status of the socket (get only)" +.It Dv SO_DOMAIN Ta "get the domain of the socket (get only)" +.It Dv SO_TYPE Ta "get the type of the socket (get only)" +.It Dv SO_PROTOCOL Ta "get the protocol number for the socket (get only)" +.It Dv SO_PROTOTYPE Ta "SunOS alias for the Linux SO_PROTOCOL (get only)" +.It Dv SO_ERROR Ta "get and clear error on the socket (get only)" +.It Dv SO_RERROR Ta "enables receive error reporting" +.It Dv SO_FIB Ta "get or set the associated FIB (routing table) for the socket" +.El +.Pp +The following options are recognized in +.Fx : +.Bl -column SO_LISTENINCQLEN -offset indent +.It Dv SO_LABEL Ta "get MAC label of the socket (get only)" +.It Dv SO_PEERLABEL Ta "get socket's peer's MAC label (get only)" +.It Dv SO_LISTENQLIMIT Ta "get backlog limit of the socket (get only)" +.It Dv SO_LISTENQLEN Ta "get complete queue length of the socket (get only)" +.It Dv SO_LISTENINCQLEN Ta "get incomplete queue length of the socket (get only)" +.It Dv SO_USER_COOKIE Ta "set the 'so_user_cookie' value for the socket (uint32_t, set only)" +.It Dv SO_TS_CLOCK Ta "set specific format of timestamp returned by SO_TIMESTAMP" +.It Dv SO_MAX_PACING_RATE Ta "set the maximum transmit rate in bytes per second for the socket" +.It Dv SO_NO_OFFLOAD Ta "disables protocol offloads" +.It Dv SO_NO_DDP Ta "disables direct data placement offload" +.It Dv SO_SPLICE Ta "splice two sockets together" +.El +.Pp +.Dv SO_DEBUG +enables debugging in the underlying protocol modules. +.Pp +.Dv SO_REUSEADDR +indicates that the rules used in validating addresses supplied +in a +.Xr bind 2 +system call should allow reuse of local addresses. +.Pp +.Dv SO_REUSEPORT +allows completely duplicate bindings by multiple processes +if they all set +.Dv SO_REUSEPORT +before binding the port. +This option permits multiple instances of a program to each +receive UDP/IP multicast or broadcast datagrams destined for the bound port. +.Pp +.Dv SO_REUSEPORT_LB +allows completely duplicate bindings by multiple sockets +if they all set +.Dv SO_REUSEPORT_LB +before binding the port. +Incoming TCP and UDP connections are distributed among the participating +listening sockets based on a hash function of local port number, and foreign IP +address and port number. +A maximum of 256 sockets can be bound to the same load-balancing group. +.Pp +.Dv SO_KEEPALIVE +enables the +periodic transmission of messages on a connected socket. +Should the +connected party fail to respond to these messages, the connection is +considered broken and processes using the socket are notified via a +.Dv SIGPIPE +signal when attempting to send data. +.Pp +.Dv SO_DONTROUTE +indicates that outgoing messages should +bypass the standard routing facilities. +Instead, messages are directed +to the appropriate network interface according to the network portion +of the destination address. +.Pp +.Dv SO_LINGER +controls the action taken when unsent messages +are queued on socket and a +.Xr close 2 +is performed. +If the socket promises reliable delivery of data and +.Dv SO_LINGER +is set, +the system will block the process on the +.Xr close 2 +attempt until it is able to transmit the data or until it decides it +is unable to deliver the information (a timeout period, termed the +linger interval, is specified in seconds in the +.Fn setsockopt +system call when +.Dv SO_LINGER +is requested). +If +.Dv SO_LINGER +is disabled and a +.Xr close 2 +is issued, the system will process the close in a manner that allows +the process to continue as quickly as possible. +.Pp +The option +.Dv SO_BROADCAST +requests permission to send broadcast datagrams +on the socket. +Broadcast was a privileged operation in earlier versions of the system. +.Pp +With protocols that support out-of-band data, the +.Dv SO_OOBINLINE +option +requests that out-of-band data be placed in the normal data input queue +as received; it will then be accessible with +.Xr recv 2 +or +.Xr read 2 +calls without the +.Dv MSG_OOB +flag. +Some protocols always behave as if this option is set. +.Pp +.Dv SO_SNDBUF +and +.Dv SO_RCVBUF +are options to adjust the normal +buffer sizes allocated for output and input buffers, respectively. +The buffer size may be increased for high-volume connections, +or may be decreased to limit the possible backlog of incoming data. +The system places an absolute maximum on these values, which is accessible +through the +.Xr sysctl 3 +MIB variable +.Dq Li kern.ipc.maxsockbuf . +.Pp +.Dv SO_SNDLOWAT +is an option to set the minimum count for output operations. +Most output operations process all of the data supplied +by the call, delivering data to the protocol for transmission +and blocking as necessary for flow control. +Nonblocking output operations will process as much data as permitted +subject to flow control without blocking, but will process no data +if flow control does not allow the smaller of the low water mark value +or the entire request to be processed. +A +.Xr select 2 +operation testing the ability to write to a socket will return true +only if the low water mark amount could be processed. +The default value for +.Dv SO_SNDLOWAT +is set to a convenient size for network efficiency, often 1024. +.Pp +.Dv SO_RCVLOWAT +is an option to set the minimum count for input operations. +In general, receive calls will block until any (non-zero) amount of data +is received, then return with the smaller of the amount available or the amount +requested. +The default value for +.Dv SO_RCVLOWAT +is 1. +If +.Dv SO_RCVLOWAT +is set to a larger value, blocking receive calls normally +wait until they have received the smaller of the low water mark value +or the requested amount. +Receive calls may still return less than the low water mark if an error +occurs, a signal is caught, or the type of data next in the receive queue +is different from that which was returned. +.Pp +.Dv SO_SNDTIMEO +is an option to set a timeout value for output operations. +It accepts a +.Vt "struct timeval" +argument with the number of seconds and microseconds +used to limit waits for output operations to complete. +If a send operation has blocked for this much time, +it returns with a partial count +or with the error +.Er EWOULDBLOCK +if no data were sent. +In the current implementation, this timer is restarted each time additional +data are delivered to the protocol, +implying that the limit applies to output portions ranging in size +from the low water mark to the high water mark for output. +.Pp +.Dv SO_RCVTIMEO +is an option to set a timeout value for input operations. +It accepts a +.Vt "struct timeval" +argument with the number of seconds and microseconds +used to limit waits for input operations to complete. +In the current implementation, this timer is restarted each time additional +data are received by the protocol, +and thus the limit is in effect an inactivity timer. +If a receive operation has been blocked for this much time without +receiving additional data, it returns with a short count +or with the error +.Er EWOULDBLOCK +if no data were received. +.Pp +.Dv SO_FIB +can be used to over-ride the default FIB (routing table) for the given socket. +The value must be from 0 to one less than the number returned from +the sysctl +.Em net.fibs . +.Pp +.Dv SO_USER_COOKIE +can be used to set the uint32_t so_user_cookie field in the socket. +The value is an uint32_t, and can be used in the kernel code that +manipulates traffic related to the socket. +The default value for the field is 0. +As an example, the value can be used as the skipto target or +pipe number in +.Nm ipfw/dummynet . +.Pp +.Dv SO_ACCEPTFILTER +places an +.Xr accept_filter 9 +on the socket, +which will filter incoming connections +on a listening stream socket before being presented for +.Xr accept 2 . +Once more, +.Xr listen 2 +must be called on the socket before +trying to install the filter on it, +or else the +.Fn setsockopt +system call will fail. +.Bd -literal +struct accept_filter_arg { + char af_name[16]; + char af_arg[256-16]; +}; +.Ed +.Pp +The +.Fa optval +argument +should point to a +.Fa struct accept_filter_arg +that will select and configure the +.Xr accept_filter 9 . +The +.Fa af_name +argument +should be filled with the name of the accept filter +that the application wishes to place on the listening socket. +The optional argument +.Fa af_arg +can be passed to the accept +filter specified by +.Fa af_name +to provide additional configuration options at attach time. +Passing in an +.Fa optval +of NULL will remove the filter. +.Pp +The +.Dv SO_NOSIGPIPE +option controls generation of the +.Dv SIGPIPE +signal normally sent +when writing to a connected socket where the other end has been +closed returns with the error +.Er EPIPE . +.Pp +If the +.Dv SO_TIMESTAMP +or +.Dv SO_BINTIME +option is enabled on a +.Dv SOCK_DGRAM +socket, the +.Xr recvmsg 2 +call may return a timestamp corresponding to when the datagram was received. +However, it may not, for example due to a resource shortage. +The +.Va msg_control +field in the +.Vt msghdr +structure points to a buffer that contains a +.Vt cmsghdr +structure followed by a +.Vt "struct timeval" +for +.Dv SO_TIMESTAMP +and +.Vt "struct bintime" +for +.Dv SO_BINTIME . +The +.Vt cmsghdr +fields have the following values for TIMESTAMP by default: +.Bd -literal + cmsg_len = CMSG_LEN(sizeof(struct timeval)); + cmsg_level = SOL_SOCKET; + cmsg_type = SCM_TIMESTAMP; +.Ed +.Pp +and for +.Dv SO_BINTIME : +.Bd -literal + cmsg_len = CMSG_LEN(sizeof(struct bintime)); + cmsg_level = SOL_SOCKET; + cmsg_type = SCM_BINTIME; +.Ed +.Pp +Additional timestamp types are available by following +.Dv SO_TIMESTAMP +with +.Dv SO_TS_CLOCK , +which requests a specific timestamp format to be returned instead of +.Dv SCM_TIMESTAMP when +.Dv SO_TIMESTAMP is enabled. +These +.Dv SO_TS_CLOCK +values are recognized in +.Fx : +.Bl -column SO_TS_CLOCK -offset indent +.It Dv SO_TS_REALTIME_MICRO Ta "realtime (SCM_TIMESTAMP, struct timeval), default" +.It Dv SO_TS_BINTIME Ta "realtime (SCM_BINTIME, struct bintime)" +.It Dv SO_TS_REALTIME Ta "realtime (SCM_REALTIME, struct timespec)" +.It Dv SO_TS_MONOTONIC Ta "monotonic time (SCM_MONOTONIC, struct timespec)" +.El +.Pp +.Dv SO_ACCEPTCONN , +.Dv SO_TYPE , +.Dv SO_PROTOCOL +(and its alias +.Dv SO_PROTOTYPE ) +and +.Dv SO_ERROR +are options used only with +.Fn getsockopt . +.Dv SO_ACCEPTCONN +returns whether the socket is currently accepting connections, +that is, whether or not the +.Xr listen 2 +system call was invoked on the socket. +.Dv SO_TYPE +returns the type of the socket, such as +.Dv SOCK_STREAM ; +it is useful for servers that inherit sockets on startup. +.Dv SO_PROTOCOL +returns the protocol number for the socket, for +.Dv AF_INET +and +.Dv AF_INET6 +address families. +.Dv SO_ERROR +returns any pending error on the socket and clears +the error status. +It may be used to check for asynchronous errors on connected +datagram sockets or for other asynchronous errors. +.Dv SO_RERROR +indicates that receive buffer overflows should be handled as errors. +Historically receive buffer overflows have been ignored and programs +could not tell if they missed messages or messages had been truncated +because of overflows. +Since programs historically do not expect to get receive overflow errors, +this behavior is not the default. +.Pp +.Dv SO_LABEL +returns the MAC label of the socket. +.Dv SO_PEERLABEL +returns the MAC label of the socket's peer. +Note that your kernel must be compiled with MAC support. +See +.Xr mac 3 +for more information. +.Pp +.Dv SO_LISTENQLIMIT +returns the maximal number of queued connections, as set by +.Xr listen 2 . +.Dv SO_LISTENQLEN +returns the number of unaccepted complete connections. +.Dv SO_LISTENINCQLEN +returns the number of unaccepted incomplete connections. +.Pp +.Dv SO_MAX_PACING_RATE +instruct the socket and underlying network adapter layers to limit the +transfer rate to the given unsigned 32-bit value in bytes per second. +.Pp +.Dv SO_NO_OFFLOAD +disables support for protocol offloads. +At present, this prevents TCP sockets from using TCP offload engines. +.Dv SO_NO_DDP +disables support for a specific TCP offload known as direct data +placement (DDP). +DDP is an offload supported by Chelsio network adapters that permits +reassembled TCP data streams to be received via zero-copy in +user-supplied buffers using +.Xr aio_read 2 . +.Pp +.Dv SO_SPLICE , +when passed to +.Fn setsockopt , +splices two sockets together using the following +.Fa optval : +.Bd -literal +struct so_splice { + int sp_fd; + off_t sp_max; + struct timeval sp_idle; +}; +.Ed +.Pp +Data received on +.Fa s +will automatically be transmitted via the socket specified in +.Fa sp_fd +without any intervention by userspace. +That is, the data will be transmitted via +.Fa sp_fd +as if userspace had called +.Xr send 2 +directly. +Splicing is a one-way operation; a given pair of sockets may be +spliced in one or both directions. +Currently only connected +.Xr tcp 4 +sockets may be spliced together. +If +.Fa sp_max +is greater than zero, the socket pair will automatically be unspliced +once that number of bytes have been transmitted. +If +.Fa sp_idle +is non-zero, the socket pair will automatically be unspliced once the +specified amount of time has elapsed since the initial call to +.Fn setsockopt . +If +.Fa sp_fd +is -1, the socket will be unspliced immediately. +A successful +.Xr select 2 , +.Xr poll 2 , +or +.Xr kqueue 2 +operation testing the ability to read from the source socket indicates +that the splicing has terminated and at least one byte is available for +reading. +When one of the sockets gets closed, splicing ends. +.Pp +When passed to +.Fn getsockopt , +the +.Dv SO_SPLICE +option returns a 64-bit integer containing the number of bytes transmitted by +the most recent splice. +That is, while the socket is spliced, the value returned will be the number +of bytes spliced so far. +When unsplicing, this value is saved and is returned until the socket is closed +or spliced again. +For example, if a splice transmits 100 bytes and is then unspliced, a subsequent +.Nm getsockopt +call will return 100 until the socket is spliced again. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn getsockopt +and +.Fn setsockopt +system calls succeed unless: +.Bl -tag -width Er +.It Bq Er EBADF +The argument +.Fa s +is not a valid descriptor. +.It Bq Er ENOTSOCK +The argument +.Fa s +is a file, not a socket. +.It Bq Er ENOPROTOOPT +The option is unknown at the level indicated. +.It Bq Er EFAULT +The address pointed to by +.Fa optval +is not in a valid part of the process address space. +For +.Fn getsockopt , +this error may also be returned if +.Fa optlen +is not in a valid part of the process address space. +.It Bq Er EINVAL +Installing an +.Xr accept_filter 9 +on a non-listening socket was attempted. +.It Bq Er ENOMEM +A memory allocation failed that was required to service the request. +.El +.Pp +The +.Fn setsockopt +system call may also return the following error: +.Bl -tag -width Er +.It Bq Er ENOBUFS +Insufficient resources were available in the system +to perform the operation. +.El +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr listen 2 , +.Xr recvmsg 2 , +.Xr socket 2 , +.Xr getprotoent 3 , +.Xr mac 3 , +.Xr sysctl 3 , +.Xr ip 4 , +.Xr ip6 4 , +.Xr sctp 4 , +.Xr tcp 4 , +.Xr protocols 5 , +.Xr sysctl 8 , +.Xr accept_filter 9 , +.Xr bintime 9 +.Sh HISTORY +The +.Fn getsockopt +and +.Fn setsockopt +system calls appeared in +.Bx 4.2 . +The +.Dv SO_SPLICE +option originated in +.Ox 4.9 +and first appeared in +.Fx 14.3 . +The +.Fx +implementation aims to be source-compatible. +.Sh BUGS +Several of the socket options should be handled at lower levels of the system. diff --git a/lib/libsys/gettimeofday.2 b/lib/libsys/gettimeofday.2 new file mode 100644 index 000000000000..4fcd4b52312b --- /dev/null +++ b/lib/libsys/gettimeofday.2 @@ -0,0 +1,149 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd April 28, 2024 +.Dt GETTIMEOFDAY 2 +.Os +.Sh NAME +.Nm gettimeofday , +.Nm settimeofday +.Nd get/set date and time +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/time.h +.Ft int +.Fn gettimeofday "struct timeval *tp" "struct timezone *tzp" +.Ft int +.Fn settimeofday "const struct timeval *tp" "const struct timezone *tzp" +.Sh DESCRIPTION +.Em Note : +The +.Nm gettimeofday +function +.Po but not +.Nm settimeofday Pc +is obsolescent. +See the +.Sx STANDARDS +section for more details. +.Pp +The system's notion of the current Greenwich time and the current time +zone is obtained with the +.Fn gettimeofday +system call, and set with the +.Fn settimeofday +system call. +The time is expressed in seconds and microseconds +since midnight (0 hour), January 1, 1970. +The resolution of the system +clock is hardware dependent, and the time may be updated continuously or +in +.Dq ticks . +If +.Fa tp +or +.Fa tzp +is NULL, the associated time +information will not be returned or set. +.Pp +The structures pointed to by +.Fa tp +and +.Fa tzp +are defined in +.In sys/time.h +as: +.Bd -literal +struct timeval { + time_t tv_sec; /* seconds */ + suseconds_t tv_usec; /* and microseconds */ +}; + +struct timezone { + int tz_minuteswest; /* minutes west of Greenwich */ + int tz_dsttime; /* type of dst correction */ +}; +.Ed +.Pp +The +.Vt timezone +structure indicates the local time zone +(measured in minutes of time westward from Greenwich), +and a flag that, if nonzero, indicates that +Daylight Saving time applies locally during +the appropriate part of the year. +The kernel generally does not track these values and they +are usually returned as zero. +Use +.Xr localtime 3 +to find the offset for the currently active timezone. +.Pp +Only the super-user may set the time of day or time zone. +If the system is running at securelevel >= 2 (see +.Xr init 8 ) , +the time may only be advanced or retarded by a maximum of one second. +This limitation is imposed to prevent a malicious super-user +from setting arbitrary time stamps on files. +The system time can be adjusted backwards without restriction using the +.Xr adjtime 2 +system call even when the system is secure. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The following error codes may be set in +.Va errno : +.Bl -tag -width Er +.It Bq Er EINVAL +The supplied +.Fa timeval +value is invalid. +.It Bq Er EPERM +A user other than the super-user attempted to set the time. +.El +.Sh SEE ALSO +.Xr date 1 , +.Xr adjtime 2 , +.Xr clock_gettime 2 , +.Xr ctime 3 , +.Xr timeradd 3 , +.Xr clocks 7 +.Sh STANDARDS +The +.Nm gettimeofday +function is considered obsolescent and its usage discouraged by +.\" XXX: This should be replaced in the future when an appropriate argument to +.\" the St macro is available: -p1003.1-2017 +.No IEEE Std 1003.1-2008, 2017 Edition (\\(LqPOSIX.1\\(Rq) . +Applications should use the +.Xr clock_gettime 2 +function instead. +.Sh HISTORY +The +.Fn gettimeofday +system call appeared in +.Bx 4.2 . diff --git a/lib/libsys/gettimeofday.c b/lib/libsys/gettimeofday.c new file mode 100644 index 000000000000..bc7990aa0457 --- /dev/null +++ b/lib/libsys/gettimeofday.c @@ -0,0 +1,51 @@ +/*- + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (c) 2012 Konstantin Belousov <kib@FreeBSD.org> + * + * 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. + */ + +#include <sys/syscall.h> +#include <sys/time.h> +#include <sys/vdso.h> +#include <errno.h> +#include "libc_private.h" + +int __gettimeofday(struct timeval *tv, struct timezone *tz); + +__weak_reference(__gettimeofday, gettimeofday); + +int +__gettimeofday(struct timeval *tv, struct timezone *tz) +{ + int error; + + error = __vdso_gettimeofday(tv, tz); + if (error == ENOSYS) { + error = __sys_gettimeofday(tv, tz); + } else if (error != 0) { + errno = error; + error = -1; + } + return (error); +} diff --git a/lib/libsys/getuid.2 b/lib/libsys/getuid.2 new file mode 100644 index 000000000000..4d3a6f88c272 --- /dev/null +++ b/lib/libsys/getuid.2 @@ -0,0 +1,88 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd December 1, 2017 +.Dt GETUID 2 +.Os +.Sh NAME +.Nm getuid , +.Nm geteuid +.Nd get user identification +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft uid_t +.Fn getuid void +.Ft uid_t +.Fn geteuid void +.Sh DESCRIPTION +The +.Fn getuid +system call returns the real user ID of the calling process. +The +.Fn geteuid +system call +returns the effective user ID of the calling process. +.Pp +The real user ID is that of the user who has invoked the program. +As the effective user ID +gives the process additional permissions during +execution of +.Dq Em set-user-ID +mode processes, +.Fn getuid +is used to determine the real-user-id of the calling process. +.Sh ERRORS +The +.Fn getuid +and +.Fn geteuid +system calls are always successful, and no return value is reserved to +indicate an error. +.Sh SEE ALSO +.Xr getgid 2 , +.Xr issetugid 2 , +.Xr setgid 2 , +.Xr setreuid 2 , +.Xr setuid 2 +.Sh STANDARDS +The +.Fn geteuid +and +.Fn getuid +system calls are expected to conform to +.St -p1003.1-90 . +.Sh HISTORY +The +.Fn getuid +function appeared in +.At v1 . +The +.Fn geteuid +function appeared in +.At v4 . diff --git a/lib/libsys/i386/Makefile.sys b/lib/libsys/i386/Makefile.sys new file mode 100644 index 000000000000..2957dc548cf8 --- /dev/null +++ b/lib/libsys/i386/Makefile.sys @@ -0,0 +1,15 @@ +SRCS+= i386_get_fsbase.c i386_get_gsbase.c i386_get_ioperm.c i386_get_ldt.c \ + i386_set_fsbase.c i386_set_gsbase.c i386_set_ioperm.c i386_set_ldt.c \ + i386_clr_watch.c i386_set_watch.c i386_vm86.c \ + rfork_thread.S + +MDASM= vfork.S cerror.S getcontext.S syscall.S + +.if ${LIB} == "sys" +MAN+= i386_get_ioperm.2 i386_get_ldt.2 i386_vm86.2 +MAN+= i386_set_watch.3 + +MLINKS+=i386_get_ioperm.2 i386_set_ioperm.2 +MLINKS+=i386_get_ldt.2 i386_set_ldt.2 +MLINKS+=i386_set_watch.3 i386_clr_watch.3 +.endif # ${LIB} == "sys" diff --git a/lib/libsys/i386/Makefile.thr b/lib/libsys/i386/Makefile.thr new file mode 100644 index 000000000000..52e861709faf --- /dev/null +++ b/lib/libsys/i386/Makefile.thr @@ -0,0 +1 @@ +SRCS+= _umtx_op_err.S diff --git a/lib/libsys/i386/SYS.h b/lib/libsys/i386/SYS.h new file mode 100644 index 000000000000..f5e0565452da --- /dev/null +++ b/lib/libsys/i386/SYS.h @@ -0,0 +1,58 @@ +/*- + * SPDX-License-Identifier: BSD-3-Clause + * + * Copyright (c) 1990 The Regents of the University of California. + * All rights reserved. + * + * This code is derived from software contributed to Berkeley by + * William Jolitz. + * + * 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. + * 3. Neither the name of the University nor the names of its contributors + * may be used to endorse or promote products derived from this software + * without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. + */ + +#include <sys/syscall.h> +#include <machine/asm.h> + +#define _SYSCALL(name) \ + mov $SYS_##name, %eax; \ + int $0x80 + +#ifndef _SYSCALL_BODY +#define _SYSCALL_BODY(name) \ + _SYSCALL(name); \ + jb HIDENAME(cerror); \ + ret +#endif + +#define RSYSCALL(name) ENTRY(__sys_##name); \ + WEAK_REFERENCE(__sys_##name, name); \ + WEAK_REFERENCE(__sys_##name, _##name); \ + _SYSCALL_BODY(name); \ + END(__sys_##name) + +#define PSEUDO(name) ENTRY(__sys_##name); \ + WEAK_REFERENCE(__sys_##name, _##name); \ + _SYSCALL_BODY(name); \ + END(__sys_##name) diff --git a/lib/libsys/i386/Symbol.sys.map b/lib/libsys/i386/Symbol.sys.map new file mode 100644 index 000000000000..6b3169336a3f --- /dev/null +++ b/lib/libsys/i386/Symbol.sys.map @@ -0,0 +1,25 @@ +FBSD_1.0 { + i386_clr_watch; + i386_get_fsbase; + i386_get_gsbase; + i386_get_ioperm; + i386_get_ldt; + i386_set_fsbase; + i386_set_gsbase; + i386_set_ioperm; + i386_set_ldt; + i386_set_watch; + i386_vm86; + rfork_thread; +}; + +FBSD_1.6 { + x86_pkru_get_perm; + x86_pkru_protect_range; + x86_pkru_set_perm; + x86_pkru_unprotect_range; +}; + +FBSDprivate_1.0 { + _vfork; +}; diff --git a/lib/libsys/i386/_umtx_op_err.S b/lib/libsys/i386/_umtx_op_err.S new file mode 100644 index 000000000000..460bd72604aa --- /dev/null +++ b/lib/libsys/i386/_umtx_op_err.S @@ -0,0 +1,39 @@ +/*- + * Copyright (C) 2008 David Xu <davidxu@freebsd.org> + * All rights reserved. + * + * 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. Neither the name of the author nor the names of its contributors + * may be used to endorse or promote products derived from this software + * without specific prior written permission. + * + * 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. + */ + +#include <machine/asm.h> +#include <sys/syscall.h> + +#define SYSCALL_ERR(x) \ + ENTRY(__CONCAT(x, _err)); \ + mov __CONCAT($SYS_,x),%eax; \ + int $0x80; \ + ret; \ + END(__CONCAT(x, _err)) + +SYSCALL_ERR(_umtx_op) + + .section .note.GNU-stack,"",%progbits diff --git a/lib/libsys/i386/cerror.S b/lib/libsys/i386/cerror.S new file mode 100644 index 000000000000..6e7015edabc4 --- /dev/null +++ b/lib/libsys/i386/cerror.S @@ -0,0 +1,63 @@ +/*- + * Copyright (c) 1990 The Regents of the University of California. + * All rights reserved. + * + * This code is derived from software contributed to Berkeley by + * William Jolitz. + * + * 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. + * 3. Neither the name of the University nor the names of its contributors + * may be used to endorse or promote products derived from this software + * without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. + */ + +#include <machine/asm.h> +#include "SYS.h" + + .globl HIDENAME(cerror) + .hidden HIDENAME(cerror) + + /* + * The __error() function is thread aware. For non-threaded + * programs and the initial thread in threaded programs, + * it returns a pointer to the global errno variable. + */ + .globl CNAME(__error) + .type CNAME(__error),@function +HIDENAME(cerror): +#ifdef PIC + PIC_PROLOGUE + pushl %eax + call PIC_PLT(CNAME(__error)) + popl %ecx + PIC_EPILOGUE +#else + pushl %eax + call CNAME(__error) + popl %ecx +#endif + movl %ecx,(%eax) + movl $-1,%eax + movl $-1,%edx + ret + + .section .note.GNU-stack,"",%progbits diff --git a/lib/libsys/i386/getcontext.S b/lib/libsys/i386/getcontext.S new file mode 100644 index 000000000000..d6b5dcd58669 --- /dev/null +++ b/lib/libsys/i386/getcontext.S @@ -0,0 +1,45 @@ +/*- + * Copyright (c) 2003 Peter Wemm <peter@FreeBSD.org> + * All rights reserved. + * + * 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. + */ + +#include <machine/asm.h> +#include <SYS.h> + +/* + * This has to be magic to handle the multiple returns. + * Otherwise, the setcontext() syscall will return here and we'll + * pop off the return address and go to the *setcontext* call. + */ + WEAK_REFERENCE(__sys_getcontext, _getcontext) + WEAK_REFERENCE(__sys_getcontext, getcontext) +ENTRY(__sys_getcontext) + movl (%esp),%ecx /* save getcontext return address */ + _SYSCALL(getcontext) + jb HIDENAME(cerror) + addl $4,%esp /* remove stale (setcontext) return address */ + jmp *%ecx /* restore return address */ +END(__sys_getcontext) + + .section .note.GNU-stack,"",%progbits diff --git a/lib/libsys/i386/i386_clr_watch.c b/lib/libsys/i386/i386_clr_watch.c new file mode 100644 index 000000000000..f01b340d81e0 --- /dev/null +++ b/lib/libsys/i386/i386_clr_watch.c @@ -0,0 +1,45 @@ +/*- + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright 2000 Brian S. Dean <bsd@bsdhome.com> + * All Rights Reserved. + * + * 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 BRIAN S. DEAN ``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 BRIAN S. DEAN 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. + */ + +#include <machine/reg.h> +#include <machine/sysarch.h> + +int +i386_clr_watch(int watchnum, struct dbreg * d) +{ + + if (watchnum < 0 || watchnum >= 4) + return -1; + + DBREG_DRX(d,7) = DBREG_DRX(d,7) & ~((0x3 << (watchnum*2)) | (0x0f << (watchnum*4+16))); + DBREG_DRX(d,watchnum) = 0; + + return 0; +} diff --git a/lib/libsys/i386/i386_get_fsbase.c b/lib/libsys/i386/i386_get_fsbase.c new file mode 100644 index 000000000000..b60c6af5ff55 --- /dev/null +++ b/lib/libsys/i386/i386_get_fsbase.c @@ -0,0 +1,36 @@ +/*- + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (c) 2005 Peter Wemm + * All rights reserved. + * + * 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. + */ + +#include <machine/sysarch.h> + +int +i386_get_fsbase(void **addr) +{ + + return (sysarch(I386_GET_FSBASE, addr)); +} diff --git a/lib/libsys/i386/i386_get_gsbase.c b/lib/libsys/i386/i386_get_gsbase.c new file mode 100644 index 000000000000..fd8187d83437 --- /dev/null +++ b/lib/libsys/i386/i386_get_gsbase.c @@ -0,0 +1,36 @@ +/*- + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (c) 2005 Peter Wemm + * All rights reserved. + * + * 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. + */ + +#include <machine/sysarch.h> + +int +i386_get_gsbase(void **addr) +{ + + return (sysarch(I386_GET_GSBASE, addr)); +} diff --git a/lib/libsys/i386/i386_get_ioperm.2 b/lib/libsys/i386/i386_get_ioperm.2 new file mode 100644 index 000000000000..decdf8379ac3 --- /dev/null +++ b/lib/libsys/i386/i386_get_ioperm.2 @@ -0,0 +1,85 @@ +.\" Copyright (c) 1998 Jonathan Lemon +.\" All rights reserved. +.\" +.\" 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. +.\" +.Dd July 27, 1998 +.Dt I386_GET_IOPERM 2 +.Os +.Sh NAME +.Nm i386_get_ioperm , +.Nm i386_set_ioperm +.Nd manage per-process access to the i386 I/O port space +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In machine/sysarch.h +.Ft int +.Fn i386_get_ioperm "unsigned int start" "unsigned int *length" "int *enable" +.Ft int +.Fn i386_set_ioperm "unsigned int start" "unsigned int length" "int enable" +.Sh DESCRIPTION +The +.Fn i386_get_ioperm +system call +will return the permission for the process' I/O port space in the +.Fa *enable +argument. +The port range starts at +.Fa start +and the number of contiguous entries will be returned in +.Fa *length . +.Pp +The +.Fn i386_set_ioperm +system call +will set access to a range of I/O ports described by the +.Fa start +and +.Fa length +arguments to the state specified by the +.Fa enable +argument. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn i386_get_ioperm +and +.Fn i386_set_ioperm +system calls +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +An invalid range was specified by the +.Fa start +or +.Fa length +arguments. +.It Bq Er EPERM +The caller of i386_set_ioperm was not the superuser. +.El +.Sh SEE ALSO +.Xr io 4 +.Sh AUTHORS +This man page was written by +.An Jonathan Lemon . diff --git a/lib/libsys/i386/i386_get_ioperm.c b/lib/libsys/i386/i386_get_ioperm.c new file mode 100644 index 000000000000..6adfe2bedf6c --- /dev/null +++ b/lib/libsys/i386/i386_get_ioperm.c @@ -0,0 +1,47 @@ +/*- + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (c) 1998 Jonathan Lemon + * All rights reserved. + * + * 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. + */ + +#include <machine/sysarch.h> + +int +i386_get_ioperm(unsigned int start, unsigned int *length, int *enable) +{ + struct i386_ioperm_args p; + int error; + + p.start = start; + p.length = *length; + p.enable = *enable; + + error = sysarch(I386_GET_IOPERM, &p); + + *length = p.length; + *enable = p.enable; + + return (error); +} diff --git a/lib/libsys/i386/i386_get_ldt.2 b/lib/libsys/i386/i386_get_ldt.2 new file mode 100644 index 000000000000..0884fd8cfea1 --- /dev/null +++ b/lib/libsys/i386/i386_get_ldt.2 @@ -0,0 +1,136 @@ +.\" Copyright (c) 1980, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd October 14, 2006 +.Dt I386_GET_LDT 2 +.Os +.Sh NAME +.Nm i386_get_ldt , +.Nm i386_set_ldt +.Nd manage i386 per-process Local Descriptor Table entries +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In machine/segments.h +.In machine/sysarch.h +.Ft int +.Fn i386_get_ldt "int start_sel" "union descriptor *descs" "int num_sels" +.Ft int +.Fn i386_set_ldt "int start_sel" "union descriptor *descs" "int num_sels" +.Sh DESCRIPTION +The +.Fn i386_get_ldt +system call +returns a list of the i386 descriptors in the current process' +LDT. +The +.Fn i386_set_ldt +system call +sets a list of i386 descriptors in the current process' +LDT. +For both routines, +.Fa start_sel +specifies the index of the selector in the LDT at which to begin and +.Fa descs +points to an array of +.Fa num_sels +descriptors to be set or returned. +.Pp +Each entry in the +.Fa descs +array can be either a segment_descriptor or gate_descriptor and are defined in +.In i386/segments.h . +These structures are defined by the architecture +as disjoint bit-fields, so care must be taken in constructing them. +.Pp +If +.Fa start_sel +is +.Em LDT_AUTO_ALLOC , +.Fa num_sels +is 1 and the descriptor pointed to by +.Fa descs +is legal, then +.Fn i386_set_ldt +will allocate a descriptor and return its +selector number. +.Pp +If +.Fa num_descs +is 1, +.Fa start_sels +is valid, and +.Fa descs +is NULL, then +.Fn i386_set_ldt +will free that descriptor +(making it available to be reallocated again later). +.Pp +If +.Fa num_descs +is 0, +.Fa start_sels +is 0 and +.Fa descs +is NULL then, as a special case, +.Fn i386_set_ldt +will free all descriptors. +.Sh RETURN VALUES +Upon successful completion, +.Fn i386_get_ldt +returns the number of descriptors currently in the LDT. +The +.Fn i386_set_ldt +system call +returns the first selector set on success. +If the kernel allocated a descriptor in the LDT, +the allocated index is returned. +Otherwise, a value of -1 is returned and the global +variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn i386_get_ldt +and +.Fn i386_set_ldt +system calls +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +An inappropriate value was used for +.Fa start_sel +or +.Fa num_sels . +.It Bq Er EACCES +The caller attempted to use a descriptor that would +circumvent protection or cause a failure. +.El +.Sh SEE ALSO +i386 Microprocessor Programmer's Reference Manual, Intel +.Sh WARNING +You can really hose your process using this. diff --git a/lib/libsys/i386/i386_get_ldt.c b/lib/libsys/i386/i386_get_ldt.c new file mode 100644 index 000000000000..8021476434d6 --- /dev/null +++ b/lib/libsys/i386/i386_get_ldt.c @@ -0,0 +1,45 @@ +/*- + * SPDX-License-Identifier: BSD-3-Clause + * + * Copyright (c) 1993 John Brezak + * All rights reserved. + * + * 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. + * 3. The name of the author may not be used to endorse or promote products + * derived from this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHOR `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 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. + */ + +#include <sys/cdefs.h> +#include <machine/segments.h> +#include <machine/sysarch.h> + +int +i386_get_ldt(int start, union descriptor *descs, int num) +{ + struct i386_ldt_args p; + + p.start = start; + p.descs = descs; + p.num = num; + + return sysarch(I386_GET_LDT, &p); +} diff --git a/lib/libsys/i386/i386_set_fsbase.c b/lib/libsys/i386/i386_set_fsbase.c new file mode 100644 index 000000000000..8420f492a5d5 --- /dev/null +++ b/lib/libsys/i386/i386_set_fsbase.c @@ -0,0 +1,36 @@ +/*- + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (c) 2005 Peter Wemm + * All rights reserved. + * + * 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. + */ + +#include <machine/sysarch.h> + +int +i386_set_fsbase(void *addr) +{ + + return (sysarch(I386_SET_FSBASE, &addr)); +} diff --git a/lib/libsys/i386/i386_set_gsbase.c b/lib/libsys/i386/i386_set_gsbase.c new file mode 100644 index 000000000000..779b2e74eb3f --- /dev/null +++ b/lib/libsys/i386/i386_set_gsbase.c @@ -0,0 +1,36 @@ +/*- + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (c) 2005 Peter Wemm + * All rights reserved. + * + * 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. + */ + +#include <machine/sysarch.h> + +int +i386_set_gsbase(void *addr) +{ + + return (sysarch(I386_SET_GSBASE, &addr)); +} diff --git a/lib/libsys/i386/i386_set_ioperm.c b/lib/libsys/i386/i386_set_ioperm.c new file mode 100644 index 000000000000..b65f62fe44bb --- /dev/null +++ b/lib/libsys/i386/i386_set_ioperm.c @@ -0,0 +1,41 @@ +/*- + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (c) 1998 Jonathan Lemon + * All rights reserved. + * + * 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. + */ + +#include <machine/sysarch.h> + +int +i386_set_ioperm(unsigned int start, unsigned int length, int enable) +{ + struct i386_ioperm_args p; + + p.start = start; + p.length = length; + p.enable = enable; + + return (sysarch(I386_SET_IOPERM, &p)); +} diff --git a/lib/libsys/i386/i386_set_ldt.c b/lib/libsys/i386/i386_set_ldt.c new file mode 100644 index 000000000000..ac363e45d769 --- /dev/null +++ b/lib/libsys/i386/i386_set_ldt.c @@ -0,0 +1,45 @@ +/*- + * SPDX-License-Identifier: BSD-3-Clause + * + * Copyright (c) 1993 John Brezak + * All rights reserved. + * + * 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. + * 3. The name of the author may not be used to endorse or promote products + * derived from this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHOR `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 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. + */ + +#include <sys/cdefs.h> +#include <machine/segments.h> +#include <machine/sysarch.h> + +int +i386_set_ldt(int start, union descriptor *descs, int num) +{ + struct i386_ldt_args p; + + p.start = start; + p.descs = descs; + p.num = num; + + return sysarch(I386_SET_LDT, &p); +} diff --git a/lib/libsys/i386/i386_set_watch.3 b/lib/libsys/i386/i386_set_watch.3 new file mode 100644 index 000000000000..265c21119c53 --- /dev/null +++ b/lib/libsys/i386/i386_set_watch.3 @@ -0,0 +1,116 @@ +.\" Copyright (c) 2000 Brian S. Dean +.\" All rights reserved. +.\" +.\" This man-page is based on a similar man-page by Jonathan Lemon +.\" which is copyrighted under the following conditions: +.\" +.\" 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. +.\" +.Dd August 24, 2000 +.Dt I386_SET_WATCH 3 +.Os +.Sh NAME +.Nm i386_clr_watch , +.Nm i386_set_watch +.Nd manage i386 debug register values +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In machine/reg.h +.In machine/sysarch.h +.Ft int +.Fn i386_clr_watch "int watchnum" "struct dbreg *d" +.Ft int +.Fn i386_set_watch "int watchnum" "unsigned int watchaddr" "int size" "int access" "struct dbreg *d" +.Sh DESCRIPTION +The +.Fn i386_clr_watch +function +will disable the indicated watch point within the specified debug +register set. +.Pp +The +.Fn i386_set_watch +function +will set up the specified debug registers as indicated by the +arguments. +The +.Fa watchnum +argument specifies which watch register is used, 0, 1, 2, 3, or \-1. +If +.Fa watchnum +is \-1, a free watch register is found and used. +If there are no free +watch registers, an error code of \-1 is returned. +The +.Fa watchaddr +argument +specifies the watch address, +.Fa size +specifies the size in bytes of the area to be watched (1, 2, or 4 bytes), +and +.Fa access +specifies the type of watch point: +.Pp +.Bd -literal -offset indent -compact +DBREG_DR7_EXEC An execution breakpoint. +DBREG_DR7_WRONLY Break only when the watch area is written to. +DBREG_DR7_RDWR Break when the watch area is read from or written + to. +.Ed +.Pp +Note that these functions do not actually set or clear breakpoints; +they manipulate the indicated debug register set. +You must use +.Xr ptrace 2 +to retrieve and install the debug register values for a process. +.Sh RETURN VALUES +On success, the +.Fn i386_clr_watch +function returns 0. +On error, \-1 returned which indicates that +.Fa watchnum +is invalid (not in the range of 0-3). +If the specified watchnum was already disabled, no error is returned. +.Pp +On success, the +.Fn i386_set_watch +function returns the +.Fa watchnum +argument, or the watchnum actually used in the case where the specified +.Fa watchnum +was \-1. +On error, the +.Fn i386_set_watch +function returns \-1 indicating that the watchpoint could not established +because either no more watchpoints are available, or +.Fa watchnum , +.Fa size , +or +.Fa access +is invalid. +.Sh SEE ALSO +.Xr ptrace 2 , +.Xr procfs 4 +.Sh AUTHORS +This man page was written by +.An Brian S. Dean . diff --git a/lib/libsys/i386/i386_set_watch.c b/lib/libsys/i386/i386_set_watch.c new file mode 100644 index 000000000000..acdcd79720e3 --- /dev/null +++ b/lib/libsys/i386/i386_set_watch.c @@ -0,0 +1,83 @@ +/*- + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright 2000 Brian S. Dean <bsd@bsdhome.com> + * All Rights Reserved. + * + * 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 BRIAN S. DEAN ``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 BRIAN S. DEAN 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. + */ + +#include <machine/reg.h> +#include <machine/sysarch.h> + +int +i386_set_watch(int watchnum, unsigned int watchaddr, int size, + int access, struct dbreg * d) +{ + int i; + unsigned int mask; + + if (watchnum == -1) { + for (i = 0, mask = 0x3; i < 4; i++, mask <<= 2) + if ((DBREG_DRX(d,7) & mask) == 0) + break; + if (i < 4) + watchnum = i; + else + return -1; + } + + switch (access) { + case DBREG_DR7_EXEC: + size = 1; /* size must be 1 for an execution breakpoint */ + /* fall through */ + case DBREG_DR7_WRONLY: + case DBREG_DR7_RDWR: + break; + default : return -1; break; + } + + /* + * we can watch a 1, 2, or 4 byte sized location + */ + switch (size) { + case 1 : mask = 0x00; break; + case 2 : mask = 0x01 << 2; break; + case 4 : mask = 0x03 << 2; break; + default : return -1; break; + } + + mask |= access; + + /* clear the bits we are about to affect */ + DBREG_DRX(d,7) &= ~((0x3 << (watchnum*2)) | (0x0f << (watchnum*4+16))); + + /* set drN register to the address, N=watchnum */ + DBREG_DRX(d,watchnum) = watchaddr; + + /* enable the watchpoint */ + DBREG_DRX(d,7) |= (0x2 << (watchnum*2)) | (mask << (watchnum*4+16)); + + return watchnum; +} diff --git a/lib/libsys/i386/i386_vm86.2 b/lib/libsys/i386/i386_vm86.2 new file mode 100644 index 000000000000..bbfb5a9b2ebc --- /dev/null +++ b/lib/libsys/i386/i386_vm86.2 @@ -0,0 +1,139 @@ +.\" Copyright (c) 1998 Jonathan Lemon +.\" All rights reserved. +.\" +.\" 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. +.\" +.Dd July 27, 1998 +.Dt I386_VM86 2 +.Os +.Sh NAME +.Nm i386_vm86 +.Nd control vm86-related functions +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In machine/sysarch.h +.In machine/vm86.h +.Ft int +.Fn i386_vm86 "int function" "void *data" +.Sh DESCRIPTION +The +.Fn i386_vm86 +system call +is used to call various vm86 related functions. +The +.Fa function +argument +can be one of the following values: +.Bl -tag -offset indent -width VM86_SET_VME +.It Dv VM86_INIT +This will initialize the kernel's vm86 parameter area for the +process, and permit the process to make vm86 calls. +The +.Fa data +argument +points to the following structure: +.Bd -literal +struct vm86_init_args { + int debug; + int cpu_type; + u_char int_map[32]; +}; +.Ed +.Pp +The +.Fa debug +argument +is used to turn on debugging code. +The +.Fa cpu_type +argument +controls the type of CPU being emulated, and is currently unimplemented. +The +.Fa int_map +argument +is a bitmap which determines whether vm86 interrupts should be handled +in vm86 mode, or reflected back to the process. +If the +.Em Nth +bit is set, the interrupt will be reflected to the process, otherwise +it will be dispatched by the vm86 interrupt table. +.It Dv VM86_INTCALL +This allows calls to be made to vm86 interrupt handlers by the process. +It effectively simulates an INT instruction. +.Fa data +should point to the following structure: +.Bd -literal +struct vm86_intcall_args { + int intnum; + struct vm86frame vmf; +}; +.Ed +.Pp +.Fa intnum +specifies the operand of INT for the simulated call. +A value of 0x10, for example, would often be used to call into the VGA BIOS. +.Fa vmf +is used to initialize CPU registers according to the calling convention for +the interrupt handler. +.It Dv VM86_GET_VME +This is used to retrieve the current state of the Pentium(r) processor's +VME (Virtual-8086 Mode Extensions) flag, which is bit 0 of CR4. +.Fa data +should be initialized to point to the following: +.Bd -literal +struct vm86_vme_args { + int state; /* status */ +}; +.Ed +.Pp +.Fa state +will contain the state of the VME flag on return. +.\" .It Dv VM86_SET_VME +.El +.Pp +vm86 mode is entered by calling +.Xr sigreturn 2 +with the correct machine context for vm86, and with the +.Dv PSL_VM +bit set. +Control returns to the process upon delivery of a signal. +.Sh RETURN VALUES +.Rv -std i386_vm86 +.Sh ERRORS +The +.Fn i386_vm86 +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The kernel does not have vm86 support, or an invalid function was specified. +.It Bq Er ENOMEM +There is not enough memory to initialize the kernel data structures. +.El +.Sh AUTHORS +.An -nosplit +This man page was written by +.An Jonathan Lemon , +and updated by +.An Bruce M Simpson . diff --git a/lib/libsys/i386/i386_vm86.c b/lib/libsys/i386/i386_vm86.c new file mode 100644 index 000000000000..fab2a3080ccd --- /dev/null +++ b/lib/libsys/i386/i386_vm86.c @@ -0,0 +1,40 @@ +/*- + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (c) 1998 Jonathan Lemon + * All rights reserved. + * + * 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. + */ + +#include <machine/sysarch.h> + +int +i386_vm86(int fcn, void *data) +{ + struct i386_vm86_args p; + + p.sub_op = fcn; + p.sub_args = (char *)data; + + return (sysarch(I386_VM86, &p)); +} diff --git a/lib/libsys/i386/rfork_thread.S b/lib/libsys/i386/rfork_thread.S new file mode 100644 index 000000000000..b37f16c930e8 --- /dev/null +++ b/lib/libsys/i386/rfork_thread.S @@ -0,0 +1,111 @@ +/*- + * Copyright (c) 2000 Peter Wemm <peter@FreeBSD.org> + * All rights reserved. + * + * 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. + */ + +#include <machine/asm.h> +/* + * With thanks to John Dyson for the original version of this. + */ + +#include <SYS.h> + +/* + * 8 12 16 20 + * rfork_thread(flags, stack_addr, start_fnc, start_arg); + * + * flags: Flags to rfork system call. See rfork(2). + * stack_addr: Top of stack for thread. + * start_fnc: Address of thread function to call in child. + * start_arg: Argument to pass to the thread function in child. + */ + +ENTRY(rfork_thread) + pushl %ebp + movl %esp, %ebp + pushl %esi + + /* + * Push thread info onto the new thread's stack + */ + movl 12(%ebp), %esi # get stack addr + + subl $4, %esi + movl 20(%ebp), %eax # get start argument + movl %eax, (%esi) + + subl $4, %esi + movl 16(%ebp), %eax # get start thread address + movl %eax, (%esi) + + /* + * Prepare and execute the thread creation syscall + */ + pushl 8(%ebp) + pushl $0 + _SYSCALL(rfork) + jb 2f + + /* + * Check to see if we are in the parent or child + */ + cmpl $0, %edx + jnz 1f + addl $8, %esp + popl %esi + movl %ebp, %esp + popl %ebp + ret + .p2align 2 + + /* + * If we are in the child (new thread), then + * set-up the call to the internal subroutine. If it + * returns, then call __exit. + */ +1: + movl %esi,%esp + popl %eax + call *%eax + addl $4, %esp + + /* + * Exit system call + */ + pushl %eax + pushl $0 + _SYSCALL(exit) + + /* + * Branch here if the thread creation fails: + */ +2: + addl $8, %esp + popl %esi + movl %ebp, %esp + popl %ebp + jmp HIDENAME(cerror) +END(rfork_thread) + + .section .note.GNU-stack,"",%progbits diff --git a/lib/libsys/i386/syscall.S b/lib/libsys/i386/syscall.S new file mode 100644 index 000000000000..bed7156e28ac --- /dev/null +++ b/lib/libsys/i386/syscall.S @@ -0,0 +1,49 @@ +/*- + * Copyright (c) 1990 The Regents of the University of California. + * All rights reserved. + * + * This code is derived from software contributed to Berkeley by + * William Jolitz. + * + * 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. + * 3. Neither the name of the University nor the names of its contributors + * may be used to endorse or promote products derived from this software + * without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. + */ + +#include <machine/asm.h> +#include "SYS.h" + +ENTRY(syscall) + pop %ecx /* rta */ + pop %eax /* syscall number */ + push %ecx + int $0x80 + push %ecx /* need to push a word to keep stack frame intact + upon return; the word must be the return address. */ + jb HIDENAME(cerror) + ret +END(syscall) + +PSEUDO(syscall) + + .section .note.GNU-stack,"",%progbits diff --git a/lib/libsys/i386/vfork.S b/lib/libsys/i386/vfork.S new file mode 100644 index 000000000000..3399b8b752de --- /dev/null +++ b/lib/libsys/i386/vfork.S @@ -0,0 +1,48 @@ +/*- + * Copyright (c) 1990 The Regents of the University of California. + * All rights reserved. + * + * This code is derived from software contributed to Berkeley by + * William Jolitz. + * + * 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. + * 3. Neither the name of the University nor the names of its contributors + * may be used to endorse or promote products derived from this software + * without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. + */ + +#include <machine/asm.h> +#include "SYS.h" + + WEAK_REFERENCE(__sys_vfork, _vfork) + WEAK_REFERENCE(__sys_vfork, vfork) +ENTRY(__sys_vfork) + popl %ecx /* my rta into ecx */ + _SYSCALL(vfork) + jb 1f + jmp *%ecx +1: + pushl %ecx + jmp HIDENAME(cerror) +END(__sys_vfork) + + .section .note.GNU-stack,"",%progbits diff --git a/lib/libsys/inotify.2 b/lib/libsys/inotify.2 new file mode 100644 index 000000000000..f94509d6f59e --- /dev/null +++ b/lib/libsys/inotify.2 @@ -0,0 +1,379 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 Klara, Inc. +.\" +.Dd May 19, 2025 +.Dt INOTIFY 2 +.Os +.Sh NAME +.Nm inotify_init , +.Nm inotify_init1 , +.Nm inotify_add_watch , +.Nm inotify_add_watch_at , +.Nm inotify_rm_watch +.Nd monitor file system events +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/inotify.h +.Ft int +.Fo inotify_init +.Fc +.Ft int +.Fo inotify_init1 +.Fa "int flags" +.Fc +.Ft int +.Fo inotify_add_watch +.Fa "int fd" +.Fa "const char *pathname" +.Fa "uint32_t mask" +.Fc +.Ft int +.Fo inotify_add_watch_at +.Fa "int fd" +.Fa "int dfd" +.Fa "const char *pathname" +.Fa "uint32_t mask" +.Fc +.Ft int +.Fo inotify_rm_watch +.Fa "int fd" +.Fa "uint32_t wd" +.Fc +.Bd -literal +struct inotify_event { + int wd; /* Watch descriptor */ + uint32_t mask; /* Event and flags */ + uint32_t cookie; /* Unique ID which links rename events */ + uint32_t len; /* Name field size, including nul bytes */ + char name[0]; /* Filename (nul-terminated) */ +}; +.Ed +.Sh DESCRIPTION +The inotify system calls provide an interface to monitor file system events. +They aim to be compatible with the Linux inotify interface. +The provided functionality is similar to the +.Dv EVFILT_VNODE +filter of the +.Xr kevent 2 +system call, but further allows monitoring of a directory without needing to +open each object in that directory. +This avoids races and reduces the number of file descriptors needed to monitor +a large file hierarchy. +.Pp +inotify allows one or more file system objects, generally files or directories, +to be watched for events, such as file open or close. +Watched objects are associated with a file descriptor returned +by +.Fn inotify_init +or +.Fn inotify_init1 . +When an event occurs, a record describing the event becomes available for +reading from the inotify file descriptor. +Each inotify descriptor thus refers to a queue of events waiting to be read. +inotify descriptors are inherited across +.Xr fork 2 +calls and may be passed to other processes via +.Xr unix 4 +sockets. +.Pp +The +.Fn inotify_init1 +system call accepts two flags. +The +.Dv IN_NONBLOCK +flag causes the inotify descriptor to be opened in non-blocking mode, such that +.Xr read 2 +calls will not block if no records are available to consume, and will instead +return +.Er EWOULDBLOCK . +The +.Dv IN_CLOEXEC +flag causes the inotify descriptor to be closed automatically when +.Xr execve 2 +is called. +.Pp +To watch a file or directory, the +.Fn inotify_add_watch +or +.Fn inotify_add_watch_at +system calls must be used. +They take a path and a mask of events to watch for, and return a +.Dq watch descriptor , +a non-negative integer which uniquely identifies the watched object within the +inotify descriptor. +.Pp +The +.Fn inotify_rm_watch +system call removes a watch from an inotify descriptor. +.Pp +When watching a directory, objects within the directory are monitored for events +as well as the directory itself. +A record describing an inotify event consists of a +.Dq struct inotify_event +followed by the name of the object in the directory being watched. +If the watched object itself generates an event, no name is present. +Extra nul bytes may follow the file name in order to provide alignment for a +subsequent record. +.Pp +The following events are defined: +.Bl -tag -width IN_CLOSE_NOWRITE +.It Dv IN_ACCESS +A file's contents were accessed, e.g., by +.Xr read 2 +.Xr copy_file_range 2 , +.Xr sendfile 2 , +or +.Xr getdirentries 2 . +.It Dv IN_ATTRIB +A file's metadata was changed, e.g., by +.Xr chmod 2 +or +.Xr unlink 2 . +.It Dv IN_CLOSE_WRITE +A file that was previously opened for writing was closed. +.It Dv IN_CLOSE_NOWRITE +A file that was previously opened read-only was closed. +.It Dv IN_CREATE +A file within a watched directory was created, e.g., by +.Xr open 2 , +.Xr mkdir 2 , +.Xr symlink 2 , +.Xr mknod 2 , +or +.Xr bind 2 . +.It Dv IN_DELETE +A file or directory within a watched directory was removed. +.It Dv IN_DELETE_SELF +The watched file or directory itself was deleted. +This event is generated only when the link count of the file drops +to zero. +.It Dv IN_MODIFY +A file's contents were modified, e.g., by +.Xr write 2 +or +.Xr copy_file_range 2 . +.It Dv IN_MOVE_SELF +The watched file or directory itself was renamed. +.It Dv IN_MOVED_FROM +A file or directory was moved from a watched directory. +.It Dv IN_MOVED_TO +A file or directory was moved into a watched directory. +A +.Xr rename 2 +call thus may generate two events, one for the old name and one for the new +name. +These are linked together by the +.Ar cookie +field in the inotify record, which can be compared to link the two records +to the same event. +.It Dv IN_OPEN +A file was opened. +.El +.Pp +Some additional flags may be set in inotify event records: +.Bl -tag -width IN_Q_OVERFLOW +.It Dv IN_IGNORED +When a watch is removed from a file, for example because it was created with the +.Dv IN_ONESHOT +flag, the file was deleted, or the watch was explicitly removed with +.Xr inotify_rm_watch 2 , +an event with this mask is generated to indicate that the watch will not +generate any more events. +Once this event is generated, the watch is automatically removed, and in +particular should not be removed manually with +.Xr inotify_rm_watch 2 . +.It Dv IN_ISDIR +When the subject of an event is a directory, this flag is set in the +.Ar mask +.It Dv IN_Q_OVERFLOW +One or more events were dropped, for example because of a kernel memory allocation +failure or because the event queue size hit a limit. +.It Dv IN_UNMOUNT +The filesystem containing the watched object was unmounted. +.El +.Pp +A number of flags may also be specified in the +.Ar mask +given to +.Fn inotify_add_watch +and +.Fn inotify_add_watch_at : +.Bl -tag -width IN_DONT_FOLLOW +.It Dv IN_DONT_FOLLOW +If +.Ar pathname +is a symbolic link, do not follow it. +.It Dv IN_EXCL_UNLINK +This currently has no effect, see the +.Sx BUGS +section. +.In Dv IN_MASK_ADD +When adding a watch to an object, and that object is already watched by the +same inotify descriptor, by default the mask of the existing watch is +overwritten. +When +.Dv IN_MASK_ADD +is specified, the mask of the existing watch is instead logically ORed with +the new mask. +.In Dv IN_MASK_CREATE +When +.Fn inotify_add watch +is used to add a watch to an object, +.Dv IN_MASK_CREATE +is specified, and that object is already watched by the same inotify descriptor, +return an error instead of updating the existing watch. +.In Dv IN_ONESHOT +Monitor the object for a single event, after which the watch is automatically +removed. +As part of removal, a +.Dv IN_IGNORED +event is generated. +.In Dv IN_ONLYDIR +When creating a watch, fail with +.Er ENOTDIR +if the path does not refer to a directory. +.El +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width 15 +.It Va vfs.inotify.max_events +The maximum number of inotify records that can be queued for a single +inotify descriptor. +Records in excess of this limit are discarded, and a single event with +mask equal to +.Dv IN_Q_OVERFLOW +will be present in the queue. +.It Va vfs.inotify.max_user_instances +The maximum number of inotify descriptors that can be created by a single +user. +.It Va vfs.inotify.max_user_watches +The maximum number of inotify watches per user. +.El +.Sh EXAMPLES +See the example program in +.Pa /usr/share/examples/inotify/inotify.c . +.Sh ERRORS +The +.Fn inotify_init +and +.Fn inotify_init1 +functions will fail if: +.Bl -tag -width Er +.It Bq Er ENFILE +The system limit on the total number of open files has been reached. +.It Bq Er EMFILE +A per-process limit on the number of open files has been reached. +.It Bq Er EMFILE +The system limit on the number of inotify descriptors has been reached. +.It Bq Er EINVAL +An unrecognized flag was passed to +.Fn inotify_init1 . +.El +.Pp +The +.Fn inotify_add_watch +and +.Fn inotify_add_watch_at +system calls will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Ar fd +parameter is not a valid file descriptor. +.It Bq Er EINVAL +The +.Ar fd +parameter is not an inotify descriptor. +.It Bq Er EINVAL +The +.Ar mask +parameter does not specify an event, or +the +.Dv IN_MASK_CREATE +and +.Dv IN_MASK_ADD +flags are both set, or an unrecognized flag was passed. +.It Bq Er ENOTDIR +The +.Ar pathname +parameter refers to a file that is not a directory, and the +.Dv IN_ONLYDIR +flag was specified. +.It Bq Er ENOSPC +The per-user limit on the total number of inotify watches has been reached. +.It Bq Er ECAPMODE +The process is in capability mode and +.Fn inotify_add_watch +was called, or +.Fn inotify_add_watch_at +was called with +.Dv AT_FDCWD +as the directory file descriptor +.Ar dfd . +.It Bq Er ENOTCAPABLE +The process is in capability mode and +.Ar pathname +contains a +.Dq .. +component leading to a directory outside the directory hierarchy specified +by +.Ar dfd . +.El +.Pp +The +.Fn inotify_rm_watch +system call will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Ar fd +parameter is not a valid file descriptor. +.It Bq Er EINVAL +The +.Ar fd +parameter is not an inotify descriptor. +.It Bq Er EINVAL +The +.Ar wd +parameter is not a valid watch descriptor. +.El +.Sh SEE ALSO +.Xr kevent 2 , +.Xr capsicum 4 +.Sh STANDARDS +The +.Nm +interface originates from Linux and is non-standard. +This implementation aims to be compatible with that of Linux and is based +on the documentation available at +.Pa https://man7.org/linux/man-pages/man7/inotify.7.html . +.Sh HISTORY +The inotify system calls first appeared in +.Fx 15.0 . +.Sh BUGS +If a file in a watched directory has multiple hard links, +an access via any hard link for that file will generate an event, even +if the accessed link belongs to an unwatched directory. +This is not the case for the Linux implementation, where only accesses +via the hard link in the watched directory will generate an event. +.Pp +If a watched directory contains multiple hard links of a file, an event +on one of the hard links will generate an inotify record for each link +in the directory. +.Pp +When a file is unlinked, no more events will be generated for that file, +even if it continues to be accessed. +By default, the Linux implementation will continue to generate events in +this case. +Thus, the +.Fx +implementation behaves as though +.Dv IN_EXCL_UNLINK +is always set. diff --git a/lib/libsys/interposing_table.c b/lib/libsys/interposing_table.c new file mode 100644 index 000000000000..31cdb1511ab8 --- /dev/null +++ b/lib/libsys/interposing_table.c @@ -0,0 +1,82 @@ +/* + * Copyright (c) 2014 The FreeBSD Foundation. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * 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(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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. + */ + +#include <sys/types.h> +#include "libc_private.h" + +#define SLOT(a, b) \ + [INTERPOS_##a] = (interpos_func_t)b +static interpos_func_t __libsys_interposing[INTERPOS_MAX] = { + SLOT(accept, __sys_accept), + SLOT(accept4, __sys_accept4), + SLOT(aio_suspend, __sys_aio_suspend), + SLOT(close, __sys_close), + SLOT(connect, __sys_connect), + SLOT(fcntl, __sys_fcntl), + SLOT(fsync, __sys_fsync), + SLOT(fork, __sys_fork), + SLOT(msync, __sys_msync), + SLOT(nanosleep, __sys_nanosleep), + SLOT(openat, __sys_openat), + SLOT(poll, __sys_poll), + SLOT(pselect, __sys_pselect), + SLOT(read, __sys_read), + SLOT(readv, __sys_readv), + SLOT(recvfrom, __sys_recvfrom), + SLOT(recvmsg, __sys_recvmsg), + SLOT(select, __sys_select), + SLOT(sendmsg, __sys_sendmsg), + SLOT(sendto, __sys_sendto), + SLOT(setcontext, __sys_setcontext), + SLOT(sigaction, __sys_sigaction), + SLOT(sigprocmask, __sys_sigprocmask), + SLOT(sigsuspend, __sys_sigsuspend), + SLOT(sigwait, __libsys_sigwait), + SLOT(sigtimedwait, __sys_sigtimedwait), + SLOT(sigwaitinfo, __sys_sigwaitinfo), + SLOT(swapcontext, __sys_swapcontext), + SLOT(wait4, __sys_wait4), + SLOT(write, __sys_write), + SLOT(writev, __sys_writev), + SLOT(kevent, __sys_kevent), + SLOT(wait6, __sys_wait6), + SLOT(ppoll, __sys_ppoll), + SLOT(fdatasync, __sys_fdatasync), + SLOT(clock_nanosleep, __sys_clock_nanosleep), + SLOT(pdfork, __sys_pdfork), +}; +#undef SLOT + +interpos_func_t * +__libsys_interposing_slot(int interposno) +{ + return (&__libsys_interposing[interposno]); +} diff --git a/lib/libsys/intro.2 b/lib/libsys/intro.2 new file mode 100644 index 000000000000..008936b278ae --- /dev/null +++ b/lib/libsys/intro.2 @@ -0,0 +1,764 @@ +.\"- +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" Copyright (c) 1980, 1983, 1986, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd April 19, 2024 +.Dt INTRO 2 +.Os +.Sh NAME +.Nm intro , +.Nm errno +.Nd introduction to system calls and their error numbers +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/syscall.h +.In errno.h +.Sh DESCRIPTION +This section contains the system calls which comprise the +.Fx +programming environment. +This page also provides an overview of common definitions and concepts +relevant to system calls, where to find a table of the system calls +currently available on your system, and their error returns. +.\".Pp +.\".Sy System call restart +.\".Pp +.\"(more later...) +.Sh DEFINITIONS +.Bl -tag -width Ds +.It Process ID +Each active process in the system is uniquely identified by a non-negative +integer called a process ID. +The range of this ID is from 0 to 99999. +.It Parent process ID +A new process is created by a currently active process +.Pq see Xr fork 2 . +The parent process ID of a process is initially the process ID of its creator. +If the creating process exits, +the parent process ID of each child is set to the ID of the calling process's +reaper +.Pq see Xr procctl 2 , +normally +.Xr init 8 . +.It Process Group +Each active process is a member of a process group that is identified by +a non-negative integer called the process group ID. +This is the process +ID of the group leader. +This grouping permits the signaling of related processes +.Pq see Xr termios 4 +and the job control mechanisms of +.Xr csh 1 . +.It Session +A session is a set of one or more process groups. +A session is created by a successful call to +.Xr setsid 2 , +which causes the caller to become the only member of the only process +group in the new session. +.It Session leader +A process that has created a new session by a successful call to +.Xr setsid 2 , +is known as a session leader. +Only a session leader may acquire a terminal as its controlling terminal +.Pq see Xr termios 4 . +.It Controlling process +A session leader with a controlling terminal is a controlling process. +.It Controlling terminal +A terminal that is associated with a session is known as the controlling +terminal for that session and its members. +.It Terminal Process Group ID +A terminal may be acquired by a session leader as its controlling terminal. +Once a terminal is associated with a session, any of the process groups +within the session may be placed into the foreground by setting +the terminal process group ID to the ID of the process group. +This facility is used +to arbitrate between multiple jobs contending for the same terminal +.Pq see Xr csh 1 and Xr tty 4 . +.It Orphaned Process Group +A process group is considered to be +.Em orphaned +if it is not under the control of a job control shell. +More precisely, a process group is orphaned +when none of its members has a parent process that is in the same session +as the group, +but is in a different process group. +Note that when a process exits, the parent process for its children +is normally changed to be +.Xr init 8 , +which is in a separate session. +Not all members of an orphaned process group are necessarily orphaned +processes +.Pq those whose creating process has exited . +The process group of a session leader is orphaned by definition. +.It Real User ID and Real Group ID +Each user on the system is identified by a positive integer +termed the real user ID. +.Pp +Each user is also a member of one or more groups. +One of these groups is distinguished from others and +used in implementing accounting facilities. +The positive +integer corresponding to this distinguished group is termed +the real group ID. +.Pp +All processes have a real user ID and real group ID. +These are initialized from the equivalent attributes +of the process that created it. +.It Effective User Id, Effective Group Id, and Group Access List +Access to system resources is governed by two values: +the effective user ID, and the group access list. +The first member of the group access list is also known as the +effective group ID. +In POSIX.1, the group access list is known as the set of supplementary +group IDs, and it is unspecified whether the effective group ID is +a member of the list. +.Pp +The effective user ID and effective group ID are initially the +process's real user ID and real group ID respectively. +Either +may be modified through execution of a set-user-ID or set-group-ID file +.Pq possibly by one its ancestors +.Pq see Xr execve 2 . +By convention, the effective group ID +.Pq the first member of the group access list +is duplicated, so that the execution of a set-group-ID program +does not result in the loss of the original +.Pq real +group ID. +.Pp +The group access list is a set of group IDs +used only in determining resource accessibility. +Access checks +are performed as described below in ``File Access Permissions''. +.It Saved Set User ID and Saved Set Group ID +When a process executes a new file, the effective user ID is set +to the owner of the file if the file is set-user-ID, and the effective +group ID +.Pq first element of the group access list +is set to the group of the file if the file is set-group-ID. +The effective user ID of the process is then recorded as the saved set-user-ID, +and the effective group ID of the process is recorded as the saved set-group-ID. +These values may be used to regain those values as the effective user +or group ID after reverting to the real ID +.Pq see Xr setuid 2 . +In POSIX.1, the saved set-user-ID and saved set-group-ID are optional, +and are used in setuid and setgid, but this does not work as desired +for the super-user. +.It Super-user +A process is recognized as a +.Em super-user +process and is granted special privileges if its effective user ID is 0. +.It Descriptor +An integer assigned by the system when a file is referenced +by +.Xr open 2 +or +.Xr dup 2 , +or when a socket is created by +.Xr pipe 2 , +.Xr socket 2 +or +.Xr socketpair 2 , +which uniquely identifies an access path to that file or socket from +a given process or any of its children. +.It File Name +Names consisting of up to +.Brq Dv NAME_MAX +characters may be used to name +an ordinary file, special file, or directory. +.Pp +These characters may be arbitrary eight-bit values, +excluding +.Dv NUL +.Pq ASCII 0 +and the +.Ql \&/ +character +.Pq slash, ASCII 47 . +.Pp +Note that it is generally unwise to use +.Ql \&* , +.Ql \&? , +.Ql \&[ +or +.Ql \&] +as part of +file names because of the special meaning attached to these characters +by the shell. +.It Path Name +A path name is a +.Dv NUL Ns -terminated +character string starting with an +optional slash +.Ql \&/ , +followed by zero or more directory names separated +by slashes, optionally followed by a file name. +The total length of a path name must be less than +.Brq Dv PATH_MAX +characters. +On some systems, this limit may be infinite. +.Pp +If a path name begins with a slash, the path search begins at the +.Em root +directory. +Otherwise, the search begins from the current working directory. +A slash by itself names the root directory. +An empty +pathname refers to the current directory. +.It Directory +A directory is a special type of file that contains entries +that are references to other files. +Directory entries are called links. +By convention, a directory +contains at least two links, +.Ql .\& +and +.Ql \&.. , +referred to as +.Em dot +and +.Em dot-dot +respectively. +Dot refers to the directory itself and +dot-dot refers to its parent directory. +.It Root Directory and Current Working Directory +Each process has associated with it a concept of a root directory +and a current working directory for the purpose of resolving path +name searches. +A process's root directory need not be the root +directory of the root file system. +.It File Access Permissions +Every file in the file system has a set of access permissions. +These permissions are used in determining whether a process +may perform a requested operation on the file +.Pq such as opening a file for writing . +Access permissions are established at the +time a file is created. +They may be changed at some later time +through the +.Xr chmod 2 +call. +.Pp +File access is broken down according to whether a file may be: read, +written, or executed. +Directory files use the execute +permission to control if the directory may be searched. +.Pp +File access permissions are interpreted by the system as +they apply to three different classes of users: the owner +of the file, those users in the file's group, anyone else. +Every file has an independent set of access permissions for +each of these classes. +When an access check is made, the system +decides if permission should be granted by checking the access +information applicable to the caller. +.Pp +Read, write, and execute/search permissions on +a file are granted to a process if: +.Pp +The process's effective user ID is that of the super-user. +Note that even the super-user cannot execute a non-executable file. +.Pp +The process's effective user ID matches the user ID of the owner +of the file and the owner permissions allow the access. +.Pp +The process's effective user ID does not match the user ID of the +owner of the file, and either the process's effective +group ID matches the group ID +of the file, or the group ID of the file is in +the process's group access list, +and the group permissions allow the access. +.Pp +Neither the effective user ID nor effective group ID +and group access list of the process +match the corresponding user ID and group ID of the file, +but the permissions for ``other users'' allow access. +.Pp +Otherwise, permission is denied. +.It Sockets and Address Families +A socket is an endpoint for communication between processes. +Each socket has queues for sending and receiving data. +.Pp +Sockets are typed according to their communications properties. +These properties include whether messages sent and received +at a socket require the name of the partner, whether communication +is reliable, the format used in naming message recipients, etc. +.Pp +Each instance of the system supports some +collection of socket types; consult +.Xr socket 2 +for more information about the types available and +their properties. +.Pp +Each instance of the system supports some number of sets of +communications protocols. +Each protocol set supports addresses +of a certain format. +An Address Family is the set of addresses +for a specific group of protocols. +Each socket has an address +chosen from the address family in which the socket was created. +.El +.Sh FILES +.Bl -inset -compact +.It Pa /usr/include/sys/syscall.h +Table of currently available system calls. +.El +.Sh ERRORS +Nearly all of the system calls provide an error number referenced via +the external identifier +.Nm errno . +This identifier is defined in +.In sys/errno.h +as: +.Pp +.Dl extern int * __error(); +.Dl #define errno (* __error()) +.Pp +The +.Va __error() +function returns a pointer to a field in the thread specific structure for +threads other than the initial thread. +For the initial thread and +non-threaded processes, +.Va __error() +returns a pointer to a global +.Nm errno +variable that is compatible with the previous definition. +.Pp +When a system call detects an error, +it returns an integer value +indicating failure +.Pq usually -1 +and sets the variable +.Nm errno +accordingly. +This allows interpretation of the failure on receiving +-1 and to take action accordingly. +Successful calls never set +.Nm errno ; +once set, it remains until another error occurs. +It should only be examined after an error. +Note that a number of system calls overload the meanings of these +error numbers, and that the meanings must be interpreted according +to the type and circumstances of the call. +.Pp +The following is a complete list of the errors and their +names as given in +.In sys/errno.h . +.Bl -hang -width Ds +.It Er 0 Em "Undefined error: 0" . +Not used. +.It Er 1 EPERM Em "Operation not permitted" . +An attempt was made to perform an operation limited to processes +with appropriate privileges or to the owner of a file or other +resources. +.It Er 2 ENOENT Em "No such file or directory" . +A component of a specified pathname did not exist, or the +pathname was an empty string. +.It Er 3 ESRCH Em "No such process" . +No process could be found corresponding to that specified by the given +process ID. +.It Er 4 EINTR Em "Interrupted system call" . +An asynchronous signal +.Pq such as Dv SIGINT or Dv SIGQUIT +was caught by the process during the execution of an interruptible +function. +If the signal handler performs a normal return, the +interrupted system call will seem to have returned the error condition. +.It Er 5 EIO Em "Input/output error" . +Some physical input or output error occurred. +This error will not be reported until a subsequent operation on the same file +descriptor and may be lost +.Pq over written +by any subsequent errors. +.It Er 6 ENXIO Em "Device not configured" . +Input or output on a special file referred to a device that did not +exist, or +made a request beyond the limits of the device. +This error may also occur when, for example, +a tape drive is not online or no disk pack is +loaded on a drive. +.It Er 7 E2BIG Em "Argument list too long" . +The number of bytes used for the argument and environment +list of the new process exceeded the current limit +.Pq Dv NCARGS in In sys/param.h . +.It Er 8 ENOEXEC Em "Exec format error" . +A request was made to execute a file +that, although it has the appropriate permissions, +was not in the format required for an +executable file. +.It Er 9 EBADF Em "Bad file descriptor" . +A file descriptor argument was out of range, referred to no open file, +or a read +.Pq write +request was made to a file that was only open for writing +.Pq reading . +.It Er 10 ECHILD Em "\&No child processes" . +A +.Xr wait 2 or Xr waitpid 2 +function was executed by a process that had no existing or unwaited-for +child processes. +.It Er 11 EDEADLK Em "Resource deadlock avoided" . +An attempt was made to lock a system resource that +would have resulted in a deadlock situation. +.It Er 12 ENOMEM Em "Cannot allocate memory" . +The new process image required more memory than was allowed by the hardware +or by system-imposed memory management constraints. +A lack of swap space is normally temporary; however, +a lack of core is not. +Soft limits may be increased to their corresponding hard limits. +.It Er 13 EACCES Em "Permission denied" . +An attempt was made to access a file in a way forbidden +by its file access permissions. +.It Er 14 EFAULT Em "Bad address" . +The system detected an invalid address in attempting to +use an argument of a call. +.It Er 15 ENOTBLK Em "Block device required" . +A block device operation was attempted on a non-block device or file. +.It Er 16 EBUSY Em "Device busy" . +An attempt to use a system resource which was in use at the time +in a manner which would have conflicted with the request. +.It Er 17 EEXIST Em "File exists" . +An existing file was mentioned in an inappropriate context, +for instance, as the new link name in a +.Xr link 2 +system call. +.It Er 18 EXDEV Em "Cross-device link" . +A hard link to a file on another file system +was attempted. +.It Er 19 ENODEV Em "Operation not supported by device" . +An attempt was made to apply an inappropriate +function to a device, +for example, +trying to read a write-only device such as a printer. +.It Er 20 ENOTDIR Em "Not a directory" . +A component of the specified pathname existed, but it was +not a directory, when a directory was expected. +.It Er 21 EISDIR Em "Is a directory" . +An attempt was made to open a directory with write mode specified. +.It Er 22 EINVAL Em "Invalid argument" . +Some invalid argument was supplied. +For example, specifying an undefined signal to a +.Xr signal 3 +function or a +.Xr kill 2 +system call. +.It Er 23 ENFILE Em "Too many open files in system" . +Maximum number of open files allowable on the system +has been reached and requests for an open cannot be satisfied +until at least one has been closed. +.It Er 24 EMFILE Em "Too many open files" . +Maximum number of file descriptors allowable in the process +has been reached and requests for an open cannot be satisfied +until at least one has been closed. +The +.Xr getdtablesize 2 +system call will obtain the current limit. +.It Er 25 ENOTTY Em "Inappropriate ioctl for device" . +A control function +.Pq see Xr ioctl 2 +was attempted for a file or +special device for which the operation was inappropriate. +.It Er 26 ETXTBSY Em "Text file busy" . +The new process was a pure procedure +.Pq shared text +file which was open for writing by another process, or +while the pure procedure file was being executed an +.Xr open 2 +call requested write access. +.It Er 27 EFBIG Em "File too large" . +The size of a file exceeded the maximum. +.It Er 28 ENOSPC Em "No space left on device" . +A +.Xr write 2 +to an ordinary file, the creation of a +directory or symbolic link, or the creation of a directory +entry failed because no more disk blocks were available +on the file system, or the allocation of an inode for a newly +created file failed because no more inodes were available +on the file system. +.It Er 29 ESPIPE Em "Illegal seek" . +An +.Xr lseek 2 +system call was issued on a socket, pipe or FIFO. +.It Er 30 EROFS Em "Read-only file system" . +An attempt was made to modify a file or directory +on a file system that was read-only at the time. +.It Er 31 EMLINK Em "Too many links" . +Maximum allowable hard links to a single file has been exceeded. +This limit is a filesystem dependent variable +.Po +.Va UFS_LINK_MAX No on Xr ufs 4 , +.Va FUSE_LINK_MAX No on Xr fusefs 4 , and +.Va TMPFS_MAX No on Xr tmpfs 4 +.Pc . +.It Er 32 EPIPE Em "Broken pipe" . +A write on a pipe, socket or FIFO for which there is no process to read +the data. +.It Er 33 EDOM Em "Numerical argument out of domain" . +A numerical input argument was outside the defined domain of the mathematical +function. +.It Er 34 ERANGE Em "Result too large" . +A numerical result of the function was too large to fit in the +available space +.Pq perhaps exceeded precision . +.It Er 35 EAGAIN Em "Resource temporarily unavailable" . +This is a temporary condition and later calls to the +same routine may complete normally. +.It Er 36 EINPROGRESS Em "Operation now in progress" . +An operation that takes a long time to complete, such as +.Xr connect 2 , +was attempted on a non-blocking object +.Pq see Xr fcntl 2 . +.It Er 37 EALREADY Em "Operation already in progress" . +An operation was attempted on a non-blocking object that already +had an operation in progress. +.It Er 38 ENOTSOCK Em "Socket operation on non-socket" . +Self-explanatory. +.It Er 39 EDESTADDRREQ Em "Destination address required" . +A required address was omitted from an operation on a socket. +.It Er 40 EMSGSIZE Em "Message too long" . +A message sent on a socket was larger than the internal message buffer +or some other network limit. +.It Er 41 EPROTOTYPE Em "Protocol wrong type for socket" . +A protocol was specified that does not support the semantics of the +socket type requested. +For example, you cannot use the ARPA Internet UDP protocol with type +.Dv SOCK_STREAM . +.It Er 42 ENOPROTOOPT Em "Protocol not available" . +A bad option or level was specified in a +.Xr getsockopt 2 +or +.Xr setsockopt 2 +call. +.It Er 43 EPROTONOSUPPORT Em "Protocol not supported" . +The protocol has not been configured into the +system or no implementation for it exists. +.It Er 44 ESOCKTNOSUPPORT Em "Socket type not supported" . +The support for the socket type has not been configured into the +system or no implementation for it exists. +.It Er 45 EOPNOTSUPP Em "Operation not supported" . +The attempted operation is not supported for the type of object referenced. +Usually this occurs when a file descriptor refers to a file or socket +that cannot support this operation, +for example, trying to +.Em accept +a connection on a datagram socket. +.It Er 46 EPFNOSUPPORT Em "Protocol family not supported" . +The protocol family has not been configured into the +system or no implementation for it exists. +.It Er 47 EAFNOSUPPORT Em "Address family not supported by protocol family" . +An address incompatible with the requested protocol was used. +For example, you should not necessarily expect to be able to use +NS addresses with ARPA Internet protocols. +.It Er 48 EADDRINUSE Em "Address already in use" . +Only one usage of each address is normally permitted. +.It Er 49 EADDRNOTAVAIL Em "Can't assign requested address" . +Normally results from an attempt to create a socket with an +address not on this machine. +.It Er 50 ENETDOWN Em "Network is down" . +A socket operation encountered a dead network. +.It Er 51 ENETUNREACH Em "Network is unreachable" . +A socket operation was attempted to an unreachable network. +.It Er 52 ENETRESET Em "Network dropped connection on reset" . +The host you were connected to crashed and rebooted. +.It Er 53 ECONNABORTED Em "Software caused connection abort" . +A connection abort was caused internal to your host machine. +.It Er 54 ECONNRESET Em "Connection reset by peer" . +A connection was forcibly closed by a peer. +This normally +results from a loss of the connection on the remote socket +due to a timeout or a reboot. +.It Er 55 ENOBUFS Em "\&No buffer space available" . +An operation on a socket or pipe was not performed because +the system lacked sufficient buffer space or because a queue was full. +.It Er 56 EISCONN Em "Socket is already connected" . +A +.Xr connect 2 +request was made on an already connected socket; or, +a +.Xr sendto 2 +or +.Xr sendmsg 2 +request on a connected socket specified a destination +when already connected. +.It Er 57 ENOTCONN Em "Socket is not connected" . +An request to send or receive data was disallowed because +the socket was not connected and +.Pq when sending on a datagram socket +no address was supplied. +.It Er 58 ESHUTDOWN Em "Can't send after socket shutdown" . +A request to send data was disallowed because the socket +had already been shut down with a previous +.Xr shutdown 2 +call. +.It Er 60 ETIMEDOUT Em "Operation timed out" . +A +.Xr connect 2 +or +.Xr send 2 +request failed because the connected party did not +properly respond after a period of time. +The timeout period is dependent on the communication protocol. +.It Er 61 ECONNREFUSED Em "Connection refused" . +No connection could be made because the target machine actively +refused it. +This usually results from trying to connect +to a service that is inactive on the foreign host. +.It Er 62 ELOOP Em "Too many levels of symbolic links" . +A path name lookup involved more than 32 +.Pq Dv MAXSYMLINKS +symbolic links. +.It Er 63 ENAMETOOLONG Em "File name too long" . +A component of a path name exceeded +.Brq Dv NAME_MAX +characters, or an entire +path name exceeded +.Brq Dv PATH_MAX +characters. +See also the description of +.Dv _PC_NO_TRUNC in Xr pathconf 2 . +.It Er 64 EHOSTDOWN Em "Host is down" . +A socket operation failed because the destination host was down. +.It Er 65 EHOSTUNREACH Em "No route to host" . +A socket operation was attempted to an unreachable host. +.It Er 66 ENOTEMPTY Em "Directory not empty" . +A directory with entries other than +.Ql .\& +and +.Ql ..\& +was supplied to a remove directory or rename call. +.It Er 67 EPROCLIM Em "Too many processes" . +.It Er 68 EUSERS Em "Too many users" . +The quota system ran out of table entries. +.It Er 69 EDQUOT Em "Disc quota exceeded" . +A +.Xr write 2 +to an ordinary file, the creation of a +directory or symbolic link, or the creation of a directory +entry failed because the user's quota of disk blocks was +exhausted, or the allocation of an inode for a newly +created file failed because the user's quota of inodes +was exhausted. +.It Er 70 ESTALE Em "Stale NFS file handle" . +An attempt was made to access an open file +.Pq on an NFS file system +which is now unavailable as referenced by the file descriptor. +This may indicate the file was deleted on the NFS server or some +other catastrophic event occurred. +.It Er 72 EBADRPC Em "RPC struct is bad" . +Exchange of RPC information was unsuccessful. +.It Er 73 ERPCMISMATCH Em "RPC version wrong" . +The version of RPC on the remote peer is not compatible with +the local version. +.It Er 74 EPROGUNAVAIL Em "RPC prog. not avail" . +The requested program is not registered on the remote host. +.It Er 75 EPROGMISMATCH Em "Program version wrong" . +The requested version of the program is not available +on the remote host +.Pq RPC . +.It Er 76 EPROCUNAVAIL Em "Bad procedure for program" . +An RPC call was attempted for a procedure which does not exist +in the remote program. +.It Er 77 ENOLCK Em "No locks available" . +A system-imposed limit on the number of simultaneous file +locks was reached. +.It Er 78 ENOSYS Em "Function not implemented" . +Attempted a system call that is not available on this +system. +.It Er 79 EFTYPE Em "Inappropriate file type or format" . +The file was the wrong type for the operation, or a data file had +the wrong format. +.It Er 80 EAUTH Em "Authentication error" . +Attempted to use an invalid authentication ticket to mount a +NFS file system. +.It Er 81 ENEEDAUTH Em "Need authenticator" . +An authentication ticket must be obtained before the given NFS +file system may be mounted. +.It Er 82 EIDRM Em "Identifier removed" . +An IPC identifier was removed while the current process was waiting on it. +.It Er 83 ENOMSG Em "No message of desired type" . +An IPC message queue does not contain a message of the desired type, or a +message catalog does not contain the requested message. +.It Er 84 EOVERFLOW Em "Value too large to be stored in data type" . +A numerical result of the function was too large to be stored in the caller +provided space. +.It Er 85 ECANCELED Em "Operation canceled" . +The scheduled operation was canceled. +.It Er 86 EILSEQ Em "Illegal byte sequence" . +While decoding a multibyte character the function came along an +invalid or an incomplete sequence of bytes or the given wide +character is invalid. +.It Er 87 ENOATTR Em "Attribute not found" . +The specified extended attribute does not exist. +.It Er 88 EDOOFUS Em "Programming error" . +A function or API is being abused in a way which could only be detected +at run-time. +.It Er 89 EBADMSG Em "Bad message" . +A corrupted message was detected. +.It Er 90 EMULTIHOP Em "Multihop attempted" . +This error code is unused, but present for compatibility with other systems. +.It Er 91 ENOLINK Em "Link has been severed" . +This error code is unused, but present for compatibility with other systems. +.It Er 92 EPROTO Em "Protocol error" . +A device or socket encountered an unrecoverable protocol error. +.It Er 93 ENOTCAPABLE Em "Capabilities insufficient" . +An operation on a capability file descriptor requires greater privilege than +the capability allows. +.It Er 94 ECAPMODE Em "Not permitted in capability mode" . +The system call or operation is not permitted for capability mode processes. +.It Er 95 ENOTRECOVERABLE Em "State not recoverable" . +The state protected by a robust mutex is not recoverable. +.It Er 96 EOWNERDEAD Em "Previous owner died" . +The owner of a robust mutex terminated while holding the mutex lock. +.It Er 97 EINTEGRITY Em "Integrity check failed" . +An integrity check such as a check-hash or a cross-correlation failed. +The integrity error falls in the kernel I/O stack between +.Er EINVAL +that identifies errors in parameters to a system call and +.Er EIO +that identifies errors with the underlying storage media. +It is typically raised by intermediate kernel layers such as a +filesystem or an in-kernel GEOM subsystem when they detect inconsistencies. +Uses include allowing the +.Xr mount 8 +command to return a different exit value to automate the running of +.Xr fsck 8 +during a system boot. +.El +.Sh SEE ALSO +.Xr intro 3 , +.Xr perror 3 +.Sh HISTORY +The +.Nm Ns Pq 2 +manual page first appeared in +.At v5 . diff --git a/lib/libsys/ioctl.2 b/lib/libsys/ioctl.2 new file mode 100644 index 000000000000..e96c5c48d097 --- /dev/null +++ b/lib/libsys/ioctl.2 @@ -0,0 +1,151 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd September 11, 2013 +.Dt IOCTL 2 +.Os +.Sh NAME +.Nm ioctl +.Nd control device +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/ioctl.h +.Ft int +.Fn ioctl "int fd" "unsigned long request" ... +.Sh DESCRIPTION +The +.Fn 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 +.Fn ioctl +requests. +The argument +.Fa fd +must be an open file descriptor. +.Pp +The third argument to +.Fn ioctl +is traditionally named +.Va "char *argp" . +Most uses of +.Fn ioctl , +however, require the third argument to be a +.Vt caddr_t +or an +.Vt int . +.Pp +An +.Fn ioctl +.Fa request +has encoded in it whether the argument is an +.Dq in +argument +or +.Dq out +argument, and the size of the argument +.Fa argp +in bytes. +Macros and defines used in specifying an ioctl +.Fa request +are located in the file +.In sys/ioctl.h . +.Sh GENERIC IOCTLS +Some generic ioctls are not implemented for all types of file +descriptors. +These include: +.Bl -tag -width "xxxxxx" +.It Dv FIONREAD int +Get the number of bytes that are immediately available for reading. +.It Dv FIONWRITE int +Get the number of bytes in the descriptor's send queue. +These bytes are data which has been written to the descriptor but +which are being held by the kernel for further processing. +The nature of the required processing depends on the underlying device. +For TCP sockets, these bytes have not yet been acknowledged by the +other side of the connection. +.It Dv FIONSPACE int +Get the free space in the descriptor's send queue. +This value is the size of the send queue minus the number of bytes +being held in the queue. +Note: while this value represents the number of bytes that may be +added to the queue, other resource limitations may cause a write +not larger than the send queue's space to be blocked. +One such limitation would be a lack of network buffers for a write +to a network connection. +.El +.Sh RETURN VALUES +If an error has occurred, a value of -1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn ioctl +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument +is not a valid descriptor. +.It Bq Er ENOTTY +The +.Fa fd +argument +is not associated with a character +special device. +.It Bq Er ENOTTY +The specified request does not apply to the kind +of object that the descriptor +.Fa fd +references. +.It Bq Er EINVAL +The +.Fa request +or +.Fa argp +argument +is not valid. +.It Bq Er EFAULT +The +.Fa argp +argument +points outside the process's allocated address space. +.El +.Sh SEE ALSO +.Xr execve 2 , +.Xr fcntl 2 , +.Xr intro 4 , +.Xr tty 4 +.Sh HISTORY +The +.Fn ioctl +function appeared in +.At v7 . diff --git a/lib/libsys/issetugid.2 b/lib/libsys/issetugid.2 new file mode 100644 index 000000000000..148fba563f71 --- /dev/null +++ b/lib/libsys/issetugid.2 @@ -0,0 +1,96 @@ +.\" $OpenBSD: issetugid.2,v 1.7 1997/02/18 00:16:09 deraadt Exp $ +.\" +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd August 25, 1996 +.Dt ISSETUGID 2 +.Os +.Sh NAME +.Nm issetugid +.Nd is current process tainted by uid or gid changes +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn issetugid void +.Sh DESCRIPTION +The +.Fn issetugid +system call returns 1 if the process environment or memory address space +is considered +.Dq tainted , +and returns 0 otherwise. +.Pp +A process is tainted if it was created as a result of an +.Xr execve 2 +system call which had either of the setuid or setgid bits set (and extra +privileges were given as a result) or if it has changed any of its real, +effective or saved user or group ID's since it began execution. +.Pp +This system call exists so that library routines (eg: libc, libtermcap) +can reliably determine if it is safe to use information +that was obtained from the user, in particular the results from +.Xr getenv 3 +should be viewed with suspicion if it is used to control operation. +.Pp +A +.Dq tainted +status is inherited by child processes as a result of the +.Xr fork 2 +system call (or other library code that calls fork, such as +.Xr popen 3 ) . +.Pp +It is assumed that a program that clears all privileges as it prepares +to execute another will also reset the environment, hence the +.Dq tainted +status will not be passed on. +This is important for programs such as +.Xr su 1 +which begin setuid but need to be able to create an untainted process. +.Sh ERRORS +The +.Fn issetugid +system call is always successful, and no return value is reserved to +indicate an error. +.Sh SEE ALSO +.Xr execve 2 , +.Xr fork 2 , +.Xr setegid 2 , +.Xr seteuid 2 , +.Xr setgid 2 , +.Xr setregid 2 , +.Xr setreuid 2 , +.Xr setuid 2 +.Sh HISTORY +The +.Fn issetugid +system call first appeared in +.Ox 2.0 +and was also implemented in +.Fx 3.0 . diff --git a/lib/libsys/jail.2 b/lib/libsys/jail.2 new file mode 100644 index 000000000000..8f8b9925c712 --- /dev/null +++ b/lib/libsys/jail.2 @@ -0,0 +1,414 @@ +.\" Copyright (c) 1999 Poul-Henning Kamp. +.\" Copyright (c) 2009 James Gritton. +.\" All rights reserved. +.\" +.\" 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. +.\" +.Dd November 29, 2023 +.Dt JAIL 2 +.Os +.Sh NAME +.Nm jail , +.Nm jail_get , +.Nm jail_set , +.Nm jail_remove , +.Nm jail_attach +.Nd create and manage system jails +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/jail.h +.Ft int +.Fn jail "struct jail *jail" +.Ft int +.Fn jail_attach "int jid" +.Ft int +.Fn jail_remove "int jid" +.In sys/uio.h +.Ft int +.Fn jail_get "struct iovec *iov" "u_int niov" "int flags" +.Ft int +.Fn jail_set "struct iovec *iov" "u_int niov" "int flags" +.Sh DESCRIPTION +The +.Fn jail +system call sets up a jail and locks the current process in it. +.Pp +The argument is a pointer to a structure describing the prison: +.Bd -literal -offset indent +struct jail { + uint32_t version; + char *path; + char *hostname; + char *jailname; + unsigned int ip4s; + unsigned int ip6s; + struct in_addr *ip4; + struct in6_addr *ip6; +}; +.Ed +.Pp +.Dq Li version +defines the version of the API in use. +.Dv JAIL_API_VERSION +is defined for the current version. +.Pp +The +.Dq Li path +pointer should be set to the directory which is to be the root of the +prison. +.Pp +The +.Dq Li hostname +pointer can be set to the hostname of the prison. +This can be changed +from the inside of the prison. +.Pp +The +.Dq Li jailname +pointer is an optional name that can be assigned to the jail +for example for management purposes. +.Pp +The +.Dq Li ip4s +and +.Dq Li ip6s +give the numbers of IPv4 and IPv6 addresses that will be passed +via their respective pointers. +.Pp +The +.Dq Li ip4 +and +.Dq Li ip6 +pointers can be set to an arrays of IPv4 and IPv6 addresses to be assigned to +the prison, or NULL if none. +IPv4 addresses must be in network byte order. +.Pp +This is equivalent to, and deprecated in favor of, the +.Fn jail_set +system call (see below), with the parameters +.Va path , +.Va host.hostname , +.Va name , +.Va ip4.addr , +and +.Va ip6.addr , +and with the +.Dv JAIL_ATTACH +flag. +.Pp +The +.Fn jail_set +system call creates a new jail, or modifies an existing one, and optionally +locks the current process in it. +Jail parameters are passed as an array of name-value pairs in the array +.Fa iov , +containing +.Fa niov +elements. +Parameter names are a null-terminated string, and values may be strings, +integers, or other arbitrary data. +Some parameters are boolean, and do not have a value (their length is zero) +but are set by the name alone with or without a +.Dq no +prefix, e.g. +.Va persist +or +.Va nopersist . +Any parameters not set will be given default values, generally based on +the current environment. +.Pp +Jails have a set of core parameters, and modules can add their own jail +parameters. +The current set of available parameters, and their formats, can be +retrieved via the +.Va security.jail.param +sysctl MIB entry. +Notable parameters include those mentioned in the +.Fn jail +description above, as well as +.Va jid +and +.Va name , +which identify the jail being created or modified. +See +.Xr jail 8 +for more information on the core jail parameters. +.Pp +The +.Fa flags +arguments consists of one or more of the following flags: +.Bl -tag -width indent +.It Dv JAIL_CREATE +Create a new jail. +If a +.Va jid +or +.Va name +parameters exists, they must not refer to an existing jail. +.It Dv JAIL_UPDATE +Modify an existing jail. +One of the +.Va jid +or +.Va name +parameters must exist, and must refer to an existing jail. +If both +.Dv JAIL_CREATE +and +.Dv JAIL_UPDATE +are set, a jail will be created if it does not yet exist, and modified if it +does exist. +.It Dv JAIL_ATTACH +In addition to creating or modifying the jail, attach the current process to +it, as with the +.Fn jail_attach +system call. +.It Dv JAIL_DYING +This is deprecated in +.Fn jail_set +and has no effect. +.El +.Pp +The +.Fn jail_get +system call retrieves jail parameters, using the same name-value list as +.Fn jail_set +in the +.Fa iov +and +.Fa niov +arguments. +The jail to read can be specified by either +.Va jid +or +.Va name +by including those parameters in the list. +If they are included but are not intended to be the search key, they +should be cleared (zero and the empty string respectively). +.Pp +The special parameter +.Va lastjid +can be used to retrieve a list of all jails. +It will fetch the jail with the jid above and closest to the passed value. +The first jail (usually but not always jid 1) can be found by passing a +.Va lastjid +of zero. +.Pp +The +.Fa flags +arguments consists of one or more following flags: +.Bl -tag -width indent +.It Dv JAIL_DYING +Allow getting a jail that is in the process of being removed. +.El +.Pp +The +.Fn jail_attach +system call attaches the current process to an existing jail, +identified by +.Fa jid . +It changes the process's root and current directories to the jail's +.Va path +directory. +.Pp +The +.Fn jail_remove +system call removes the jail identified by +.Fa jid . +It will kill all processes belonging to the jail, and remove any children +of that jail. +.Sh RETURN VALUES +If successful, +.Fn jail , +.Fn jail_set , +and +.Fn jail_get +return a non-negative integer, termed the jail identifier (JID). +They return \-1 on failure, and set +.Va errno +to indicate the error. +.Pp +.Rv -std jail_attach jail_remove +.Sh ERRORS +The +.Fn jail +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +This process is not allowed to create a jail, either because it is not +the super-user, or because it would exceed the jail's +.Va children.max +limit. +.It Bq Er EFAULT +.Fa jail +points to an address outside the allocated address space of the process. +.It Bq Er EINVAL +The version number of the argument is not correct. +.It Bq Er EAGAIN +No free JID could be found. +.El +.Pp +The +.Fn jail_set +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +This process is not allowed to create a jail, either because it is not +the super-user, or because it would exceed the jail's +.Va children.max +limit. +.It Bq Er EPERM +A jail parameter was set to a less restrictive value then the current +environment. +.It Bq Er EFAULT +.Fa Iov , +or one of the addresses contained within it, +points to an address outside the allocated address space of the process. +.It Bq Er ENOENT +The jail referred to by a +.Va jid +or +.Va name +parameter does not exist, and the +.Dv JAIL_CREATE +flag is not set. +.It Bq Er ENOENT +The jail referred to by a +.Va jid +is not accessible by the process, because the process is in a different +jail. +.It Bq Er EEXIST +The jail referred to by a +.Va jid +or +.Va name +parameter exists, and the +.Dv JAIL_UPDATE +flag is not set. +.It Bq Er EINVAL +A supplied parameter is the wrong size. +.It Bq Er EINVAL +A supplied parameter is out of range. +.It Bq Er EINVAL +A supplied string parameter is not null-terminated. +.It Bq Er EINVAL +A supplied parameter name does not match any known parameters. +.It Bq Er EINVAL +One of the +.Dv JAIL_CREATE +or +.Dv JAIL_UPDATE +flags is not set. +.It Bq Er ENAMETOOLONG +A supplied string parameter is longer than allowed. +.It Bq Er EAGAIN +There are no jail IDs left. +.El +.Pp +The +.Fn jail_get +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EFAULT +.Fa Iov , +or one of the addresses contained within it, +points to an address outside the allocated address space of the process. +.It Bq Er ENOENT +The jail referred to by a +.Va jid +or +.Va name +parameter does not exist. +.It Bq Er ENOENT +The jail referred to by a +.Va jid +is not accessible by the process, because the process is in a different +jail. +.It Bq Er ENOENT +The +.Va lastjid +parameter is greater than the highest current jail ID. +.It Bq Er EINVAL +A supplied parameter is the wrong size. +.It Bq Er EINVAL +A supplied parameter name does not match any known parameters. +.El +.Pp +The +.Fn jail_attach +and +.Fn jail_remove +system calls +will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +A user other than the super-user attempted to attach to or remove a jail. +.It Bq Er EINVAL +The jail specified by +.Fa jid +does not exist. +.El +.Pp +Further +.Fn jail , +.Fn jail_set , +and +.Fn jail_attach +call +.Xr chroot 2 +internally, so they can fail for all the same reasons. +Please consult the +.Xr chroot 2 +manual page for details. +.Sh SEE ALSO +.Xr chdir 2 , +.Xr chroot 2 , +.Xr jail 8 +.Sh HISTORY +The +.Fn jail +system call appeared in +.Fx 4.0 . +The +.Fn jail_attach +system call appeared in +.Fx 5.1 . +The +.Fn jail_set , +.Fn jail_get , +and +.Fn jail_remove +system calls appeared in +.Fx 8.0 . +.Sh AUTHORS +The jail feature was written by +.An Poul-Henning Kamp +for R&D Associates +who contributed it to +.Fx . +.An James Gritton +added the extensible jail parameters and hierarchical jails. diff --git a/lib/libsys/kcmp.2 b/lib/libsys/kcmp.2 new file mode 100644 index 000000000000..5491e09b918b --- /dev/null +++ b/lib/libsys/kcmp.2 @@ -0,0 +1,230 @@ +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2024 The FreeBSD Foundation +.\" +.\" This documentation was written by +.\" Mark Johnston <markj@FreeBSD.org> under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" 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 AUTHORS 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 AUTHORS 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. +.\" +.Dd January 23, 2024 +.Dt KCMP 2 +.Os +.Sh NAME +.Nm kcmp +.Nd compare two kernel objects +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn kcmp "pid_t pid1" "pid_t pid2" "int type" "uintptr_t idx1" "uintptr_t idx2" +.Sh DESCRIPTION +The +.Nm +system call allows the caller to determine whether the two processes with +PIDs +.Fa pid1 +and +.Fa pid2 +reference the same kernel object. +The +.Fa type +parameter specifies the type of object, and +.Fa idx1 +and +.Fa idx2 +are identifiers which refer to some object in the context of process +.Fa pid1 +and +.Fa pid2 , +respectively. +.Pp +The following values for +.Fa type +may be specified: +.Bl -tag -width KCMP_FILE +.It Dv KCMP_FILE +Compare two file descriptions referred to by file descriptors +.Fa idx1 +and +.Fa idx2 . +They may be equivalent if, for example, one of the descriptors was +created by applying +.Xr dup 2 +to the other descriptor. +.It Dv KCMP_FILEOBJ +Perform a +.Dq deep comparison +of the file descriptions referred to by file descriptors +.Fa idx1 +and +.Fa idx2 . +This tests whether the underlying object referred to by the file descriptions +is the same. +For example, if the same filesystem path is opened twice, the kernel will create +two separate file descriptions to back the two file descriptors, but they will +refer to the same underlying object, a +.Xr vnode 9 . +When compared using the +.Dv KCMP_FILE +type, these descriptors will be different, but using the +.Dv KCMP_FILEOBJ +type, they will be equal (assuming that the path was not unlinked in between +the two opens). +.It Dv KCMP_FILES +Determine whether the two processes share the same file descriptor table. +This will be the case if one of the processes was created by +.Xr rfork 2 +without specifying the +.Dv RFFDG +flag. +The +.Fa idx1 +and +.Fa idx2 +parameters are ignored. +.It Dv KCMP_SIGHAND +Determine whether the two processes share the same signal handler table. +This will be the case if one of the processes was created using the +.Dv RFSIGSHARE +flag to +.Xr rfork 2 . +The +.Fa idx1 +and +.Fa idx2 +parameters are ignored. +.It Dv KCMP_VM +Determine whether the two processes share a virtual memory address space. +This may be the case if one of the processes created the other using +.Xr vfork 2 +or +.Xr rfork 2 +with the +.Dv RFMEM +flag. +The +.Fa idx1 +and +.Fa idx2 +parameters are ignored. +.El +The caller of +.Nm +must have permission to debug both processes, otherwise the system call +will fail. +.Sh RETURN VALUES +If +.Fa idx1 +and +.Fa idx2 +refer to the same object, +.Nm +returns 0. +If the object referred to by +.Fa pid1 +and +.Fa idx1 +is less or greater than the object referred to by +.Fa pid2 +and +.Fa idx2 , +.Nm +returns the values 1 and 2, respectively. +The order is defined internally by the kernel and is stable until the system +reboots. +If the two objects cannot be compared for some reason, +.Nm +returns 3. +For example, if +.Fa type +is +.Dv KCMP_FILEOBJ +and +.Fa idx1 +and +.Fa idx2 +are different descriptor types, e.g., a socket and a file, then +.Nm +will return 3. +.Pp +If an error occurs, the value -1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +.Nm +may fail with the following errors: +.Bl -tag -width Er +.It Bq Er ENODEV +.Dv KCMP_FILEOBJ +was specified and +.Fa idx1 +refers to a file descriptor which does not implement a comparison operator. +.It Bq Er EINVAL +The value of +.Fa type +is invalid. +.It Bq Er EBADF +One of the file descriptors referred to by +.Fa idx1 +or +.Fa idx2 +is not valid. +.It Bq Er ESRCH +One of the processes referred to by +.Fa pid1 +or +.Fa pid2 +does not exist or is not visible (e.g., due to jail restrictions). +.It Bq Er EPERM +The caller does not have permission to access one of the processes referred to +by +.Fa pid1 +or +.Fa pid2 . +.El +.Sh SEE ALSO +.Xr dup 2 , +.Xr fcntl 2 , +.Xr fork 2 , +.Xr rfork 2 , +.Xr vfork 2 +.Sh STANDARDS +The +.Nm +system call originated in Linux. +This implementation aims to be source-compatible with the Linux implementation. +.Fx +implements only a subset of the possible values for +.Fa type +supported in Linux. +More values may be added in the future. +The +.Dv KCMP_FILEOBJ +type is a FreeBSD extension. +.Sh HISTORY +The +.Nm +function was introduced in +.Fx 14.1 . diff --git a/lib/libsys/kenv.2 b/lib/libsys/kenv.2 new file mode 100644 index 000000000000..9f179ff2faa6 --- /dev/null +++ b/lib/libsys/kenv.2 @@ -0,0 +1,191 @@ +.\" +.\" Copyright (C) 2002 Chad David <davidc@FreeBSD.org>. All rights reserved. +.\" +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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. +.\" +.Dd June 20, 2021 +.Dt KENV 2 +.Os +.Sh NAME +.Nm kenv +.Nd kernel environment +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In kenv.h +.Ft int +.Fn kenv "int action" "const char *name" "char *value" "int len" +.Sh DESCRIPTION +The +.Fn kenv +system call manipulates kernel environment variables. +It supports the well known userland actions of getting, setting and unsetting +environment variables, as well as the ability to dump all of the entries in +the kernel environment. +.Pp +The +.Fa action +argument can be one of the following: +.Bl -tag -width ".Dv KENV_DUMP_LOADER" +.It Dv KENV_GET +Get the +.Fa value +of the variable with the given +.Fa name . +The size of the +.Fa value +buffer is given by +.Fa len , +which should be at least +.Dv KENV_MVALLEN ++ 1 bytes to avoid truncation and to ensure NUL termination. +.It Dv KENV_SET +Set or add a variable. +The +.Fa name +and +.Fa value +are limited to +.Dv KENV_MNAMELEN +and +.Dv KENV_MVALLEN +characters, respectively +.Pq not including the NUL terminator. +The +.Fa len +argument indicates the length of the +.Fa value +and must include the NUL terminator. +This option is only available to the superuser. +.It Dv KENV_UNSET +Unset the variable with the given +.Fa name . +The +.Fa value +and +.Fa len +arguments are ignored. +This option is only available to the superuser. +.It Dv KENV_DUMP +Dump as much of the dynamic kernel environment as will fit in +.Fa value , +whose size is given in +.Fa len . +If +.Fa value +is +.Dv NULL , +.Fn kenv +will return the number of bytes required to copy out the entire environment. +The +.Fa name +is ignored. +.It Dv KENV_DUMP_LOADER +Dump the static environment provided by +.Xr loader 8 , +with semantics identical to +.Dv KENV_DUMP . +Duplicate and malformed variables originally present in this environment are +discarded by the kernel and will not appear in the output. +.It Dv KENV_DUMP_STATIC +Dump the static environment defined by the kernel +.Xr config 5 . +The semantics are identical to +.Dv KENV_DUMP_LOADER . +.El +.Sh RETURN VALUES +The +.Fn kenv +system call returns 0 if successful in the case of +.Dv KENV_SET +and +.Dv KENV_UNSET , +and the number of bytes copied into +.Fa value +in the case of +.Dv KENV_DUMP +and +.Dv KENV_GET . +If an error occurs, a value of \-1 is returned and +the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn kenv +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa action +argument +is not a valid option, or the length of the +.Fa value +is less than 1 for a +.Dv KENV_SET . +.It Bq Er ENOENT +No value could be found for +.Fa name +for a +.Dv KENV_GET +or +.Dv KENV_UNSET . +.It Bq Er ENOENT +The requested environment is not available for a +.Dv KENV_DUMP_LOADER +or +.Dv KENV_DUMP_STATIC . +The kernel is configured to destroy these environments by default. +.It Bq Er EPERM +A user other than the superuser attempted to set or unset a kernel +environment variable. +.It Bq Er EFAULT +A bad address was encountered while attempting to copy in user arguments +or copy out value(s). +.It Bq Er ENAMETOOLONG +The +.Fa name +or the +.Fa value +is longer than +.Dv KENV_MNAMELEN +or +.Dv KENV_MVALLEN +characters, respectively, or +.Fa len +did not include the NUL terminator for a +.Dv KENV_SET . +.El +.Sh SEE ALSO +.Xr kenv 1 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Chad David Aq Mt davidc@FreeBSD.org . +.Pp +The +.Fn kenv +system call was written by +.An Maxime Henrion Aq Mt mux@FreeBSD.org . diff --git a/lib/libsys/kill.2 b/lib/libsys/kill.2 new file mode 100644 index 000000000000..bc2f3e03a726 --- /dev/null +++ b/lib/libsys/kill.2 @@ -0,0 +1,156 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd December 1, 2019 +.Dt KILL 2 +.Os +.Sh NAME +.Nm kill +.Nd send signal to a process +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In signal.h +.Ft int +.Fn kill "pid_t pid" "int sig" +.Sh DESCRIPTION +The +.Fn kill +system call sends the signal given by +.Fa sig +to +.Fa pid , +a +process or a group of processes. +The +.Fa sig +argument +may be one of the signals specified in +.Xr sigaction 2 +or it may be 0, in which case +error checking is performed but no +signal is actually sent. +This can be used to check the validity of +.Fa pid . +.Pp +For a process to have permission to send a signal to a process designated +by +.Fa pid , +the user must be the super-user, or +the real or saved user ID of the receiving process must match +the real or effective user ID of the sending process. +A single exception is the signal SIGCONT, which may always be sent +to any process with the same session ID as the sender. +In addition, if the +.Va security.bsd.conservative_signals +.Xr sysctl 9 +is set to 1, the user is not a super-user, and +the receiver is set-uid, then +only job control and terminal control signals may +be sent (in particular, only SIGKILL, SIGINT, SIGTERM, SIGALRM, +SIGSTOP, SIGTTIN, SIGTTOU, SIGTSTP, SIGHUP, SIGUSR1, SIGUSR2). +.Bl -tag -width Ds +.It \&If Fa pid No \&is greater than zero : +The +.Fa sig +signal +is sent to the process whose ID is equal to +.Fa pid . +.It \&If Fa pid No \&is zero : +The +.Fa sig +signal +is sent to all processes whose group ID is equal +to the process group ID of the sender, and for which the +process has permission; +this is a variant of +.Xr killpg 2 . +.It \&If Fa pid No \&is -1 : +If the user has super-user privileges, +the signal is sent to all processes excluding +system processes +(with +.Dv P_SYSTEM +flag set), +process with ID 1 +(usually +.Xr init 8 ) , +and the process sending the signal. +If the user is not the super user, the signal is sent to all processes +which the caller has permissions to, excluding the process sending the signal. +No error is returned if any process could be signaled. +.El +.Pp +If the process number is negative but not -1, +the signal is sent to all processes whose process group ID +is equal to the absolute value of the process number. +This is a variant of +.Xr killpg 2 . +.Sh RETURN VALUES +.Rv -std kill +.Sh ERRORS +The +.Fn kill +system call +will fail and no signal will be sent if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa sig +argument +is not a valid signal number. +.It Bq Er ESRCH +No process or process group can be found corresponding to that specified by +.Fa pid . +.It Bq Er EPERM +The sending process does not have permission to send +.Va sig +to any receiving process. +.El +.Sh SEE ALSO +.Xr getpgrp 2 , +.Xr getpid 2 , +.Xr killpg 2 , +.Xr sigaction 2 , +.Xr sigqueue 2 , +.Xr raise 3 , +.Xr init 8 +.Sh STANDARDS +The +.Fn kill +system call is expected to conform to +.St -p1003.1-90 . +.Sh HISTORY +A version of the +.Fn kill +function appeared in +.At v3 . +The signal number was added to the +.Fn kill +function in +.At v4 . diff --git a/lib/libsys/kldfind.2 b/lib/libsys/kldfind.2 new file mode 100644 index 000000000000..5ede0d1e1464 --- /dev/null +++ b/lib/libsys/kldfind.2 @@ -0,0 +1,83 @@ +.\" +.\" Copyright (c) 1999 Chris Costello +.\" All rights reserved. +.\" +.\" 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. +.\" +.Dd March 3, 1999 +.Dt KLDFIND 2 +.Os +.Sh NAME +.Nm kldfind +.Nd returns the fileid of a kld file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/linker.h +.Ft int +.Fn kldfind "const char *file" +.Sh DESCRIPTION +The +.Fn kldfind +system call +returns the fileid of the kld file referenced by +.Fa file . +.Sh RETURN VALUES +The +.Fn kldfind +system call +returns the fileid of the kld file referenced by +.Fa file . +Upon error, +.Fn kldfind +returns -1 and sets +.Va errno +to indicate the error. +.Sh ERRORS +.Va errno +is set to the following if +.Fn kldfind +fails: +.Bl -tag -width Er +.It Bq Er EFAULT +The data required for this operation could not be read from the kernel space. +.It Bq Er ENOENT +The file specified is not loaded in the kernel. +.El +.Sh SEE ALSO +.Xr kldfirstmod 2 , +.Xr kldload 2 , +.Xr kldnext 2 , +.Xr kldstat 2 , +.Xr kldsym 2 , +.Xr kldunload 2 , +.Xr modfind 2 , +.Xr modfnext 2 , +.Xr modnext 2 , +.Xr modstat 2 , +.Xr kld 4 , +.Xr kldstat 8 +.Sh HISTORY +The +.Nm kld +interface first appeared in +.Fx 3.0 . diff --git a/lib/libsys/kldfirstmod.2 b/lib/libsys/kldfirstmod.2 new file mode 100644 index 000000000000..b6dbab2c94b7 --- /dev/null +++ b/lib/libsys/kldfirstmod.2 @@ -0,0 +1,73 @@ +.\" +.\" Copyright (c) 1999 Chris Costello +.\" All rights reserved. +.\" +.\" 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. +.\" +.Dd March 3, 1999 +.Dt KLDFIRSTMOD 2 +.Os +.Sh NAME +.Nm kldfirstmod +.Nd "return first module id from the kld file specified" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/linker.h +.Ft int +.Fn kldfirstmod "int fileid" +.Sh DESCRIPTION +The +.Fn kldfirstmod +system call returns the module id pertaining to the first module referenced by +.Fa fileid . +.Sh RETURN VALUES +The +.Fn kldfirstmod +will return the id of the first module referenced by +.Fa fileid +or 0 if there are no references. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ENOENT +The kld file referenced by +.Fa fileid +was not found. +.El +.Sh SEE ALSO +.Xr kldfind 2 , +.Xr kldload 2 , +.Xr kldnext 2 , +.Xr kldstat 2 , +.Xr kldsym 2 , +.Xr kldunload 2 , +.Xr modfind 2 , +.Xr modfnext 2 , +.Xr modnext 2 , +.Xr modstat 2 , +.Xr kld 4 , +.Xr kldstat 8 +.Sh HISTORY +The +.Nm kld +interface first appeared in +.Fx 3.0 . diff --git a/lib/libsys/kldload.2 b/lib/libsys/kldload.2 new file mode 100644 index 000000000000..63a13c328d58 --- /dev/null +++ b/lib/libsys/kldload.2 @@ -0,0 +1,93 @@ +.\" +.\" Copyright (c) 1999 Chris Costello +.\" All rights reserved. +.\" +.\" 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. +.\" +.Dd March 3, 1999 +.Dt KLDLOAD 2 +.Os +.Sh NAME +.Nm kldload +.Nd load KLD files into the kernel +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/linker.h +.Ft int +.Fn kldload "const char *file" +.Sh DESCRIPTION +The +.Fn kldload +system call +loads a kld file into the kernel using the kernel linker. +.Sh RETURN VALUES +The +.Fn kldload +system call +returns the fileid of the kld file which was loaded into the kernel. +If an error occurs, +.Fn kldload +will return -1 and set +.Va errno +to indicate the error. +.Sh ERRORS +The named file is loaded unless: +.Bl -tag -width Er +.It Bq Er EPERM +You do not have access to read the file or link it with the kernel. +You should be the root user to be able to use the +.Nm kld +system calls. +.It Bq Er EFAULT +Bad address encountered when adding kld info into the kernel space. +.It Bq Er ENOMEM +There is no memory to load the file into the kernel. +.It Bq Er ENOENT +The file was not found. +.It Bq Er ENOEXEC +The file format of +.Fa file +was unrecognized. +.It Bq Er EEXIST +The supplied +.Fa file +has already been loaded. +.El +.Sh SEE ALSO +.Xr kldfind 2 , +.Xr kldfirstmod 2 , +.Xr kldnext 2 , +.Xr kldstat 2 , +.Xr kldsym 2 , +.Xr kldunload 2 , +.Xr modfind 2 , +.Xr modfnext 2 , +.Xr modnext 2 , +.Xr modstat 2 , +.Xr kld 4 , +.Xr kldload 8 +.Sh HISTORY +The +.Nm kld +interface first appeared in +.Fx 3.0 . diff --git a/lib/libsys/kldnext.2 b/lib/libsys/kldnext.2 new file mode 100644 index 000000000000..28b14dfc3035 --- /dev/null +++ b/lib/libsys/kldnext.2 @@ -0,0 +1,86 @@ +.\" +.\" Copyright (c) 1999 Chris Costello +.\" All rights reserved. +.\" +.\" 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. +.\" +.Dd February 22, 2006 +.Dt KLDNEXT 2 +.Os +.Sh NAME +.Nm kldnext +.Nd return the fileid of the next kld file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/linker.h +.Ft int +.Fn kldnext "int fileid" +.Sh DESCRIPTION +The +.Fn kldnext +system call +returns the fileid of the next kld file (that is, the one after +.Fa fileid ) +or 0 if +.Fa fileid +is the last file loaded. +To get the fileid of the first kld file, pass +.Fa fileid +of 0 to +.Fn kldnext . +.Sh RETURN VALUES +The +.Fn kldnext +system call +returns the fileid of the next kld file or 0 if successful. +Otherwise +.Fn kldnext +returns the value \-1 and sets the global variable +.Va errno +to indicate the error. +.Sh ERRORS +The only error set by +.Fn kldnext +is +.Er ENOENT , +which is set when +.Fa fileid +refers to a kld file that does not exist (is not loaded). +.Sh SEE ALSO +.Xr kldfind 2 , +.Xr kldfirstmod 2 , +.Xr kldload 2 , +.Xr kldstat 2 , +.Xr kldsym 2 , +.Xr kldunload 2 , +.Xr modfind 2 , +.Xr modfnext 2 , +.Xr modnext 2 , +.Xr modstat 2 , +.Xr kld 4 , +.Xr kldstat 8 +.Sh HISTORY +The +.Nm kld +interface first appeared in +.Fx 3.0 . diff --git a/lib/libsys/kldstat.2 b/lib/libsys/kldstat.2 new file mode 100644 index 000000000000..111323a0da8d --- /dev/null +++ b/lib/libsys/kldstat.2 @@ -0,0 +1,130 @@ +.\" +.\" Copyright (c) 1999 Chris Costello +.\" All rights reserved. +.\" +.\" 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. +.\" +.Dd March 28, 2012 +.Dt KLDSTAT 2 +.Os +.Sh NAME +.Nm kldstat +.Nd get status of kld file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/linker.h +.Ft int +.Fn kldstat "int fileid" "struct kld_file_stat *stat" +.Sh DESCRIPTION +The +.Fn kldstat +system call writes the info for the file referred to by +.Fa fileid +into +.Fa stat . +.Bd -literal +struct kld_file_stat { + int version; /* set to sizeof(struct kld_file_stat) */ + char name[MAXPATHLEN]; + int refs; + int id; + caddr_t address; + size_t size; + char pathname[MAXPATHLEN]; +}; +.Ed +.Bl -tag -width XXXaddress +.It version +This field is set to the size of the structure mentioned above by the code +calling +.Fn kldstat , +and not +.Fn kldstat +itself. +.It name +The name of the file referred to by +.Fa fileid . +.It refs +The number of modules referenced by +.Fa fileid . +.It id +The id of the file specified in +.Fa fileid . +.It address +The load address of the kld file. +.It size +The amount of memory in bytes allocated by the file. +.It pathname +The full name of the file referred to by +.Fa fileid , +including the path. +.El +.Sh RETURN VALUES +.Rv -std kldstat +.Sh ERRORS +The information for the file referred to by +.Fa fileid +is filled into the structure pointed to by +.Fa stat +unless: +.Bl -tag -width Er +.It Bq Er ENOENT +The file was not found (probably not loaded). +.It Bq Er EINVAL +The version specified in the +.Fa version +field of stat is not the proper version. +You would need to rebuild world, the +kernel, or your application, if this error occurs, given that you did properly +fill in the +.Fa version +field. +.It Bq Er EFAULT +There was a problem copying one, some, or all of the fields into +.Fa stat +in the +.Xr copyout 9 +function. +.El +.Sh SEE ALSO +.Xr kldfind 2 , +.Xr kldfirstmod 2 , +.Xr kldload 2 , +.Xr kldnext 2 , +.Xr kldsym 2 , +.Xr kldunload 2 , +.Xr modfind 2 , +.Xr modfnext 2 , +.Xr modnext 2 , +.Xr modstat 2 , +.Xr kld 4 , +.Xr kldstat 8 +.Sh HISTORY +The +.Nm kld +interface first appeared in +.Fx 3.0 . +.Sh BUGS +The pathname may not be accurate if the file system mounts have +changed since the module was loaded, or if this function is called +within a chrooted environment. diff --git a/lib/libsys/kldsym.2 b/lib/libsys/kldsym.2 new file mode 100644 index 000000000000..641fc26c38ec --- /dev/null +++ b/lib/libsys/kldsym.2 @@ -0,0 +1,118 @@ +.\" Copyright (c) 2001 Chris Costello <chris@FreeBSD.org> +.\" All rights reserved. +.\" +.\" 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. +.\" +.Dd October 17, 2016 +.Dt KLDSYM 2 +.Os +.Sh NAME +.Nm kldsym +.Nd look up address by symbol name in a KLD +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/linker.h +.Ft int +.Fn kldsym "int fileid" "int cmd" "void *data" +.Sh DESCRIPTION +The +.Fn kldsym +system call returns the address of the symbol specified in +.Fa data +in the module specified by +.Fa fileid . +If +.Fa fileid +is 0, all loaded modules are searched. +Currently, the only +.Fa cmd +implemented is +.Dv KLDSYM_LOOKUP . +.Pp +The +.Fa data +argument is of the following structure: +.Bd -literal -offset indent +struct kld_sym_lookup { + int version; /* sizeof(struct kld_sym_lookup) */ + char *symname; /* Symbol name we are looking up */ + u_long symvalue; + size_t symsize; +}; +.Ed +.Pp +The +.Va version +member is to be set +by the code calling +.Fn kldsym +to +.Fn sizeof "struct kld_sym_lookup" . +The next two members, +.Va version +and +.Va symname , +are specified by the user. +The last two, +.Va symvalue +and +.Va symsize , +are filled in by +.Fn kldsym +and contain the address associated with +.Va symname +and the size of the data it points to, respectively. +.Sh RETURN VALUES +.Rv -std kldsym +.Sh ERRORS +The +.Fn kldsym +system call will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value in +.Fa data->version +or +.Fa cmd . +.It Bq Er ENOENT +The +.Fa fileid +argument +is invalid, +or the specified symbol could not be found. +.El +.Sh SEE ALSO +.Xr kldfind 2 , +.Xr kldfirstmod 2 , +.Xr kldload 2 , +.Xr kldnext 2 , +.Xr kldunload 2 , +.Xr modfind 2 , +.Xr modnext 2 , +.Xr modstat 2 , +.Xr kld 4 +.Sh HISTORY +The +.Fn kldsym +system call first appeared in +.Fx 3.0 . diff --git a/lib/libsys/kldunload.2 b/lib/libsys/kldunload.2 new file mode 100644 index 000000000000..c89f869e9eeb --- /dev/null +++ b/lib/libsys/kldunload.2 @@ -0,0 +1,91 @@ +.\" +.\" Copyright (c) 1999 Chris Costello +.\" All rights reserved. +.\" +.\" 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. +.\" +.Dd December 25, 2008 +.Dt KLDUNLOAD 2 +.Os +.Sh NAME +.Nm kldunload , kldunloadf +.Nd unload kld files +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/linker.h +.Ft int +.Fn kldunload "int fileid" +.Ft int +.Fn kldunloadf "int fileid" "int flags" +.Sh DESCRIPTION +The +.Fn kldunload +system call +unloads a kld file from the kernel that was previously linked via +.Xr kldload 2 . +.Pp +The +.Fn kldunloadf +system call accepts an additional flags argument, which may be one of +.Dv LINKER_UNLOAD_NORMAL , +giving the same behavior as +.Fn kldunload , +or +.Dv LINKER_UNLOAD_FORCE , +which causes the unload to ignore a failure to quiesce the module. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The file referred to by +.Fa fileid +is unloaded unless: +.Bl -tag -width Er +.It Bq Er EPERM +You do not have access to unlink the file from the kernel. +.It Bq Er ENOENT +The file was not found. +.It Bq Er EBUSY +You attempted to unload a file linked by the kernel. +.It Bq Er EINVAL +The +.Fn kldunloadf +system call was passed invalid flags. +.El +.Sh SEE ALSO +.Xr kldfind 2 , +.Xr kldfirstmod 2 , +.Xr kldload 2 , +.Xr kldnext 2 , +.Xr kldstat 2 , +.Xr kldsym 2 , +.Xr modfind 2 , +.Xr modfnext 2 , +.Xr modnext 2 , +.Xr modstat 2 , +.Xr kld 4 , +.Xr kldunload 8 +.Sh HISTORY +The +.Nm kld +interface first appeared in +.Fx 3.0 . diff --git a/lib/libsys/kqueue.2 b/lib/libsys/kqueue.2 new file mode 100644 index 000000000000..d6e949baa24c --- /dev/null +++ b/lib/libsys/kqueue.2 @@ -0,0 +1,904 @@ +.\" Copyright (c) 2000 Jonathan Lemon +.\" All rights reserved. +.\" +.\" 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 ``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. +.\" +.Dd March 26, 2023 +.Dt KQUEUE 2 +.Os +.Sh NAME +.Nm kqueue , +.Nm kevent +.Nd kernel event notification mechanism +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/event.h +.Ft int +.Fn kqueue "void" +.Ft int +.Fn kqueuex "u_int flags" +.Ft int +.Fn kqueue1 "int flags" +.Ft int +.Fo kevent +.Fa "int kq" +.Fa "const struct kevent *changelist" +.Fa "int nchanges" +.Fa "struct kevent *eventlist" +.Fa "int nevents" +.Fa "const struct timespec *timeout" +.Fc +.Fn EV_SET "kev" ident filter flags fflags data udata +.Sh DESCRIPTION +The +.Fn kqueue +system call +provides a generic method of notifying the user when an event +happens or a condition holds, based on the results of small +pieces of kernel code termed filters. +A kevent is identified by the (ident, filter) pair; there may only +be one unique kevent per kqueue. +.Pp +The filter is executed upon the initial registration of a kevent +in order to detect whether a preexisting condition is present, and is also +executed whenever an event is passed to the filter for evaluation. +If the filter determines that the condition should be reported, +then the kevent is placed on the kqueue for the user to retrieve. +.Pp +The filter is also run when the user attempts to retrieve the kevent +from the kqueue. +If the filter indicates that the condition that triggered +the event no longer holds, the kevent is removed from the kqueue and +is not returned. +.Pp +Multiple events which trigger the filter do not result in multiple +kevents being placed on the kqueue; instead, the filter will aggregate +the events into a single struct kevent. +Calling +.Fn close +on a file descriptor will remove any kevents that reference the descriptor. +.Pp +The +.Fn kqueue +system call +creates a new kernel event queue and returns a descriptor. +The queue is not inherited by a child created with +.Xr fork 2 . +However, if +.Xr rfork 2 +is called without the +.Dv RFFDG +flag, then the descriptor table is shared, +which will allow sharing of the kqueue between two processes. +.Pp +The +.Fn kqueuex +system call also creates a new kernel event queue, and additionally takes +a +.Fa flags +argument, which is a bitwise-inclusive OR of the following flags: +.Bl -tag -width "KQUEUE_CLOEXEC" +.It Dv KQUEUE_CLOEXEC +The returned file descriptor is automatically closed on +.Xr execve 2 +.El +.Pp +The +.Fn kqueue +system call is equivalent to calling +.Fn kqueuex +with +.Fa flags +set to 0. +.Pp +The +.Fn kqueue1 +function exists for compatibility with +.Nx . +The +.Fa flags +argument accepts zero or more of the following values: +.Bl -tag -width O_CLOEXEC +.It Dv O_CLOEXEC +The returned file descriptor is automatically closed on +.Xr execve 2 +.El +.Pp +The +.Fn kevent +system call +is used to register events with the queue, and return any pending +events to the user. +The +.Fa changelist +argument +is a pointer to an array of +.Va kevent +structures, as defined in +.In sys/event.h . +All changes contained in the +.Fa changelist +are applied before any pending events are read from the queue. +The +.Fa nchanges +argument +gives the size of +.Fa changelist . +The +.Fa eventlist +argument +is a pointer to an array of kevent structures. +The +.Fa nevents +argument +determines the size of +.Fa eventlist . +When +.Fa nevents +is zero, +.Fn kevent +will return immediately even if there is a +.Fa timeout +specified unlike +.Xr select 2 . +If +.Fa timeout +is a non-NULL pointer, it specifies a maximum interval to wait +for an event, which will be interpreted as a struct timespec. +If +.Fa timeout +is a NULL pointer, +.Fn kevent +waits indefinitely. +To effect a poll, the +.Fa timeout +argument should be non-NULL, pointing to a zero-valued +.Va timespec +structure. +The same array may be used for the +.Fa changelist +and +.Fa eventlist . +.Pp +The +.Fn EV_SET +macro is provided for ease of initializing a +kevent structure. +.Pp +The +.Va kevent +structure is defined as: +.Bd -literal +struct kevent { + uintptr_t ident; /* identifier for this event */ + short filter; /* filter for event */ + u_short flags; /* action flags for kqueue */ + u_int fflags; /* filter flag value */ + int64_t data; /* filter data value */ + void *udata; /* opaque user data identifier */ + uint64_t ext[4]; /* extensions */ +}; +.Ed +.Pp +The fields of +.Fa struct kevent +are: +.Bl -tag -width "Fa filter" +.It Fa ident +Value used to identify this event. +The exact interpretation is determined by the attached filter, +but often is a file descriptor. +.It Fa filter +Identifies the kernel filter used to process this event. +The pre-defined +system filters are described below. +.It Fa flags +Actions to perform on the event. +.It Fa fflags +Filter-specific flags. +.It Fa data +Filter-specific data value. +.It Fa udata +Opaque user-defined value passed through the kernel unchanged. +.It Fa ext +Extended data passed to and from kernel. +The meaning of the +.Fa ext[0] +and +.Fa ext[1] +members is defined by the filter. +If a filter does not use them, +these members are passed through the kernel unchanged. +The +.Fa ext[2] +and +.Fa ext[3] +members are always passed through the kernel unchanged, +providing additional user-defined values. +.El +.Pp +The +.Va flags +field can contain the following values: +.Bl -tag -width EV_KEEPUDATA +.It Dv EV_ADD +Adds the event to the kqueue. +Re-adding an existing event +will modify the parameters of the original event, and not result +in a duplicate entry. +Adding an event automatically enables it, +unless overridden by the EV_DISABLE flag. +.It Dv EV_ENABLE +Permit +.Fn kevent +to return the event if it is triggered. +.It Dv EV_DISABLE +Disable the event so +.Fn kevent +will not return it. +The filter itself is not disabled. +.It Dv EV_DISPATCH +Disable the event source immediately after delivery of an event. +See +.Dv EV_DISABLE +above. +.It Dv EV_DELETE +Removes the event from the kqueue. +Events which are attached to +file descriptors are automatically deleted on the last close of +the descriptor. +.It Dv EV_RECEIPT +This flag is useful for making bulk changes to a kqueue without draining +any pending events. +When passed as input, it forces +.Dv EV_ERROR +to always be returned. +When a filter is successfully added the +.Va data +field will be zero. +Note that if this flag is encountered and there is no remaining space in +.Fa eventlist +to hold the +.Dv EV_ERROR +event, then subsequent changes will not get processed. +.It Dv EV_ONESHOT +Return only the first occurrence of the filter +being triggered. +After the user retrieves the event from the kqueue, +it is deleted. +.It Dv EV_CLEAR +Reset the state of the event after it is retrieved by the user. +This is useful for filters which report state transitions +instead of the current state. +Note that some filters may automatically +set this flag internally. +.It Dv EV_EOF +Filters may set this flag to indicate filter-specific EOF condition. +.It Dv EV_ERROR +See +.Sx RETURN VALUES +below. +.It Dv EV_KEEPUDATA +Preserve the +.Fa udata +associated with an existing event. +This allows other aspects of the event to be modified without requiring the +caller to know the +.Fa udata +value previously registered with the event. +This is especially useful with +.Dv NOTE_TRIGGER +or +.Dv EV_ENABLE . +This flag may not be used with +.Dv EV_ADD . +.El +.Pp +The predefined system filters are listed below. +Arguments may be passed to and from the filter via the +.Va fflags +and +.Va data +fields in the kevent structure. +.Bl -tag -width "Dv EVFILT_PROCDESC" +.It Dv EVFILT_READ +Takes a descriptor as the identifier, and returns whenever +there is data available to read. +The behavior of the filter is slightly different depending +on the descriptor type. +.Bl -tag -width 2n +.It Sockets +Sockets which have previously been passed to +.Xr listen 2 +return when there is an incoming connection pending. +.Va data +contains the size of the listen backlog. +.Pp +Other socket descriptors return when there is data to be read, +subject to the +.Dv SO_RCVLOWAT +value of the socket buffer. +This may be overridden with a per-filter low water mark at the +time the filter is added by setting the +.Dv NOTE_LOWAT +flag in +.Va fflags , +and specifying the new low water mark in +.Va data . +On return, +.Va data +contains the number of bytes of protocol data available to read. +.Pp +If the read direction of the socket has shutdown, then the filter +also sets +.Dv EV_EOF +in +.Va flags , +and returns the socket error (if any) in +.Va fflags . +It is possible for EOF to be returned (indicating the connection is gone) +while there is still data pending in the socket buffer. +.It Vnodes +Returns when the file pointer is not at the end of file. +.Va data +contains the offset from current position to end of file, +and may be negative. +.Pp +This behavior is different from +.Xr poll 2 , +where read events are triggered for regular files unconditionally. +This event can be triggered unconditionally by setting the +.Dv NOTE_FILE_POLL +flag in +.Va fflags . +.It "Fifos, Pipes" +Returns when the there is data to read; +.Va data +contains the number of bytes available. +.Pp +When the last writer disconnects, the filter will set +.Dv EV_EOF +in +.Va flags . +This will be cleared by the filter when a new writer connects, +at which point the +filter will resume waiting for data to become available before +returning. +.It "BPF devices" +Returns when the BPF buffer is full, the BPF timeout has expired, or +when the BPF has +.Dq immediate mode +enabled and there is any data to read; +.Va data +contains the number of bytes available. +.It Eventfds +Returns when the counter is greater than 0; +.Va data +contains the counter value, which must be cast to +.Vt uint64_t . +.It Kqueues +Returns when pending events are present on the queue; +.Va data +contains the number of events available. +.El +.It Dv EVFILT_WRITE +Takes a descriptor as the identifier, and returns whenever +it is possible to write to the descriptor. +For sockets, pipes +and fifos, +.Va data +will contain the amount of space remaining in the write buffer. +The filter will set +.Dv EV_EOF +when the reader disconnects, and for the fifo case, this will be cleared +when a new reader connects. +Note that this filter is not supported for vnodes. +.Pp +For sockets, the low water mark and socket error handling is +identical to the +.Dv EVFILT_READ +case. +.Pp +For eventfds, +.Va data +will contain the maximum value that can be added to the counter +without blocking. +.Pp +For BPF devices, when the descriptor is attached to an interface the filter +always indicates that it is possible to write and +.Va data +will contain the MTU size of the underlying interface. +.It Dv EVFILT_EMPTY +Takes a descriptor as the identifier, and returns whenever +there is no remaining data in the write buffer. +.It Dv EVFILT_AIO +Events for this filter are not registered with +.Fn kevent +directly but are registered via the +.Va aio_sigevent +member of an asynchronous I/O request when it is scheduled via an +asynchronous I/O system call such as +.Fn aio_read . +The filter returns under the same conditions as +.Fn aio_error . +For more details on this filter see +.Xr sigevent 3 and +.Xr aio 4 . +.It Dv EVFILT_VNODE +Takes a file descriptor as the identifier and the events to watch for in +.Va fflags , +and returns when one or more of the requested events occurs on the descriptor. +The events to monitor are: +.Bl -tag -width "Dv NOTE_CLOSE_WRITE" +.It Dv NOTE_ATTRIB +The file referenced by the descriptor had its attributes changed. +.It Dv NOTE_CLOSE +A file descriptor referencing the monitored file, was closed. +The closed file descriptor did not have write access. +.It Dv NOTE_CLOSE_WRITE +A file descriptor referencing the monitored file, was closed. +The closed file descriptor had write access. +.Pp +This note, as well as +.Dv NOTE_CLOSE , +are not activated when files are closed forcibly by +.Xr unmount 2 or +.Xr revoke 2 . +Instead, +.Dv NOTE_REVOKE +is sent for such events. +.It Dv NOTE_DELETE +The +.Fn unlink +system call was called on the file referenced by the descriptor. +.It Dv NOTE_EXTEND +For regular file, the file referenced by the descriptor was extended. +.Pp +For directory, reports that a directory entry was added or removed, +as the result of rename operation. +The +.Dv NOTE_EXTEND +event is not reported when a name is changed inside the directory. +.It Dv NOTE_LINK +The link count on the file changed. +In particular, the +.Dv NOTE_LINK +event is reported if a subdirectory was created or deleted inside +the directory referenced by the descriptor. +.It Dv NOTE_OPEN +The file referenced by the descriptor was opened. +.It Dv NOTE_READ +A read occurred on the file referenced by the descriptor. +.It Dv NOTE_RENAME +The file referenced by the descriptor was renamed. +.It Dv NOTE_REVOKE +Access to the file was revoked via +.Xr revoke 2 +or the underlying file system was unmounted. +.It Dv NOTE_WRITE +A write occurred on the file referenced by the descriptor. +.El +.Pp +On return, +.Va fflags +contains the events which triggered the filter. +.It Dv EVFILT_PROC +Takes the process ID to monitor as the identifier and the events to watch for +in +.Va fflags , +and returns when the process performs one or more of the requested events. +If a process can normally see another process, it can attach an event to it. +The events to monitor are: +.Bl -tag -width "Dv NOTE_TRACKERR" +.It Dv NOTE_EXIT +The process has exited. +The exit status will be stored in +.Va data +in the same format as the status returned by +.Xr wait 2 . +.It Dv NOTE_FORK +The process has called +.Fn fork . +.It Dv NOTE_EXEC +The process has executed a new process via +.Xr execve 2 +or a similar call. +.It Dv NOTE_TRACK +Follow a process across +.Fn fork +calls. +The parent process registers a new kevent to monitor the child process +using the same +.Va fflags +as the original event. +The child process will signal an event with +.Dv NOTE_CHILD +set in +.Va fflags +and the parent PID in +.Va data . +.Pp +If the parent process fails to register a new kevent +.Pq usually due to resource limitations , +it will signal an event with +.Dv NOTE_TRACKERR +set in +.Va fflags , +and the child process will not signal a +.Dv NOTE_CHILD +event. +.El +.Pp +On return, +.Va fflags +contains the events which triggered the filter. +.It Dv EVFILT_PROCDESC +Takes the process descriptor created by +.Xr pdfork 2 +to monitor as the identifier and the events to watch for in +.Va fflags , +and returns when the associated process performs one or more of the +requested events. +The events to monitor are: +.Bl -tag -width "Dv NOTE_EXIT" +.It Dv NOTE_EXIT +The process has exited. +The exit status will be stored in +.Va data . +.El +.Pp +On return, +.Va fflags +contains the events which triggered the filter. +.It Dv EVFILT_SIGNAL +Takes the signal number to monitor as the identifier and returns +when the given signal is delivered to the process. +This coexists with the +.Fn signal +and +.Fn sigaction +facilities, and has a lower precedence. +The filter will record +all attempts to deliver a signal to a process, even if the signal has +been marked as +.Dv SIG_IGN , +except for the +.Dv SIGCHLD +signal, which, if ignored, will not be recorded by the filter. +Event notification happens after normal +signal delivery processing. +.Va data +returns the number of times the signal has occurred since the last call to +.Fn kevent . +This filter automatically sets the +.Dv EV_CLEAR +flag internally. +.It Dv EVFILT_TIMER +Establishes an arbitrary timer identified by +.Va ident . +When adding a timer, +.Va data +specifies the moment to fire the timer (for +.Dv NOTE_ABSTIME ) +or the timeout period. +The timer will be periodic unless +.Dv EV_ONESHOT +or +.Dv NOTE_ABSTIME +is specified. +On return, +.Va data +contains the number of times the timeout has expired since the last call to +.Fn kevent . +For non-monotonic timers, this filter automatically sets the +.Dv EV_CLEAR +flag internally. +.Pp +The filter accepts the following flags in the +.Va fflags +argument: +.Bl -tag -width "Dv NOTE_MSECONDS" +.It Dv NOTE_SECONDS +.Va data +is in seconds. +.It Dv NOTE_MSECONDS +.Va data +is in milliseconds. +.It Dv NOTE_USECONDS +.Va data +is in microseconds. +.It Dv NOTE_NSECONDS +.Va data +is in nanoseconds. +.It Dv NOTE_ABSTIME +The specified expiration time is absolute. +.El +.Pp +If +.Va fflags +is not set, the default is milliseconds. +On return, +.Va fflags +contains the events which triggered the filter. +.Pp +Periodic timers with a specified timeout of 0 will be silently adjusted to +timeout after 1 of the time units specified by the requested precision in +.Va fflags . +If an absolute time is specified that has already passed, then it is treated as +if the current time were specified and the event will fire as soon as possible. +.Pp +If an existing timer is re-added, the existing timer will be +effectively canceled (throwing away any undelivered record of previous +timer expiration) and re-started using the new parameters contained in +.Va data +and +.Va fflags . +.Pp +There is a system wide limit on the number of timers +which is controlled by the +.Va kern.kq_calloutmax +sysctl. +.It Dv EVFILT_USER +Establishes a user event identified by +.Va ident +which is not associated with any kernel mechanism but is triggered by +user level code. +The lower 24 bits of the +.Va fflags +may be used for user defined flags and manipulated using the following: +.Bl -tag -width "Dv NOTE_FFLAGSMASK" +.It Dv NOTE_FFNOP +Ignore the input +.Va fflags . +.It Dv NOTE_FFAND +Bitwise AND +.Va fflags . +.It Dv NOTE_FFOR +Bitwise OR +.Va fflags . +.It Dv NOTE_FFCOPY +Copy +.Va fflags . +.It Dv NOTE_FFCTRLMASK +Control mask for +.Va fflags . +.It Dv NOTE_FFLAGSMASK +User defined flag mask for +.Va fflags . +.El +.Pp +A user event is triggered for output with the following: +.Bl -tag -width "Dv NOTE_FFLAGSMASK" +.It Dv NOTE_TRIGGER +Cause the event to be triggered. +.El +.Pp +On return, +.Va fflags +contains the users defined flags in the lower 24 bits. +.El +.Sh CANCELLATION BEHAVIOUR +If +.Fa nevents +is non-zero, i.e., the function is potentially blocking, the call +is a cancellation point. +Otherwise, i.e., if +.Fa nevents +is zero, the call is not cancellable. +Cancellation can only occur before any changes are made to the kqueue, +or when the call was blocked and no changes to the queue were requested. +.Sh RETURN VALUES +The +.Fn kqueue +system call +creates a new kernel event queue and returns a file descriptor. +If there was an error creating the kernel event queue, a value of -1 is +returned and errno set. +.Pp +The +.Fn kevent +system call +returns the number of events placed in the +.Fa eventlist , +up to the value given by +.Fa nevents . +If an error occurs while processing an element of the +.Fa changelist +and there is enough room in the +.Fa eventlist , +then the event will be placed in the +.Fa eventlist +with +.Dv EV_ERROR +set in +.Va flags +and the system error in +.Va data . +Otherwise, +.Dv -1 +will be returned, and +.Dv errno +will be set to indicate the error condition. +If the time limit expires, then +.Fn kevent +returns 0. +.Sh EXAMPLES +.Bd -literal -compact +#include <sys/event.h> +#include <err.h> +#include <fcntl.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> + +int +main(int argc, char **argv) +{ + struct kevent event; /* Event we want to monitor */ + struct kevent tevent; /* Event triggered */ + int kq, fd, ret; + + if (argc != 2) + err(EXIT_FAILURE, "Usage: %s path\en", argv[0]); + fd = open(argv[1], O_RDONLY); + if (fd == -1) + err(EXIT_FAILURE, "Failed to open '%s'", argv[1]); + + /* Create kqueue. */ + kq = kqueue(); + if (kq == -1) + err(EXIT_FAILURE, "kqueue() failed"); + + /* Initialize kevent structure. */ + EV_SET(&event, fd, EVFILT_VNODE, EV_ADD | EV_CLEAR, NOTE_WRITE, + 0, NULL); + /* Attach event to the kqueue. */ + ret = kevent(kq, &event, 1, NULL, 0, NULL); + if (ret == -1) + err(EXIT_FAILURE, "kevent register"); + + for (;;) { + /* Sleep until something happens. */ + ret = kevent(kq, NULL, 0, &tevent, 1, NULL); + if (ret == -1) { + err(EXIT_FAILURE, "kevent wait"); + } else if (ret > 0) { + if (tevent.flags & EV_ERROR) + errx(EXIT_FAILURE, "Event error: %s", strerror(event.data)); + else + printf("Something was written in '%s'\en", argv[1]); + } + } + + /* kqueues are destroyed upon close() */ + (void)close(kq); + (void)close(fd); +} +.Ed +.Sh ERRORS +The +.Fn kqueue +system call fails if: +.Bl -tag -width Er +.It Bq Er ENOMEM +The kernel failed to allocate enough memory for the kernel queue. +.It Bq Er ENOMEM +The +.Dv RLIMIT_KQUEUES +rlimit +(see +.Xr getrlimit 2 ) +for the current user would be exceeded. +.It Bq Er EMFILE +The per-process descriptor table is full. +.It Bq Er ENFILE +The system file table is full. +.El +.Pp +The +.Fn kevent +system call fails if: +.Bl -tag -width Er +.It Bq Er EACCES +The process does not have permission to register a filter. +.It Bq Er EFAULT +There was an error reading or writing the +.Va kevent +structure. +.It Bq Er EBADF +The specified descriptor is invalid. +.It Bq Er EINTR +A signal was delivered before the timeout expired and before any +events were placed on the kqueue for return. +.It Bq Er EINTR +A cancellation request was delivered to the thread, but not yet handled. +.It Bq Er EINVAL +The specified time limit or filter is invalid. +.It Bq Er EINVAL +The specified length of the event or change lists is negative. +.It Bq Er ENOENT +The event could not be found to be modified or deleted. +.It Bq Er ENOMEM +No memory was available to register the event +or, in the special case of a timer, the maximum number of +timers has been exceeded. +This maximum is configurable via the +.Va kern.kq_calloutmax +sysctl. +.It Bq Er ESRCH +The specified process to attach to does not exist. +.El +.Pp +When +.Fn kevent +call fails with +.Er EINTR +error, all changes in the +.Fa changelist +have been applied. +.Sh SEE ALSO +.Xr aio_error 2 , +.Xr aio_read 2 , +.Xr aio_return 2 , +.Xr poll 2 , +.Xr read 2 , +.Xr select 2 , +.Xr sigaction 2 , +.Xr write 2 , +.Xr pthread_setcancelstate 3 , +.Xr signal 3 +.Rs +.%A Jonathan Lemon +.%T "Kqueue: A Generic and Scalable Event Notification Facility" +.%I USENIX Association +.%B Proceedings of the FREENIX Track: 2001 USENIX Annual Technical Conference +.%D June 25-30, 2001 +.\".http://www.usenix.org/event/usenix01/freenix01/full_papers/lemon/lemon.pdf +.Re +.Sh HISTORY +The +.Fn kqueue +and +.Fn kevent +system calls first appeared in +.Fx 4.1 . +The +.Fn kqueuex +system call +and +.Fn kevent1 +function first appeared in +.Fx 14.0 . +.Sh AUTHORS +The +.Fn kqueue +system and this manual page were written by +.An Jonathan Lemon Aq Mt jlemon@FreeBSD.org . +.Sh BUGS +.Pp +In versions older than +.Fx 12.0 , +.In sys/event.h +failed to parse without including +.In sys/types.h +manually. diff --git a/lib/libsys/ktrace.2 b/lib/libsys/ktrace.2 new file mode 100644 index 000000000000..c12caca438fe --- /dev/null +++ b/lib/libsys/ktrace.2 @@ -0,0 +1,204 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd November 2, 2022 +.Dt KTRACE 2 +.Os +.Sh NAME +.Nm ktrace +.Nd process tracing +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/time.h +.In sys/uio.h +.In sys/ktrace.h +.Ft int +.Fn ktrace "const char *tracefile" "int ops" "int trpoints" "int pid" +.Sh DESCRIPTION +The +.Fn ktrace +system call enables or disables tracing of one or more processes. +Users may only trace their own processes. +Only the super-user can trace setuid or setgid programs. +.Pp +The +.Fa tracefile +argument +gives the pathname of the file to be used for tracing. +The file must exist and be a regular file writable by the calling process. +All trace records are always appended to the file, +so the file must be truncated to zero length to discard +previous trace data. +If tracing points are being disabled (see KTROP_CLEAR below), +.Fa tracefile +may be NULL. +.Pp +The +.Fa ops +argument specifies the requested ktrace operation. +The defined operations are: +.Bl -column KTRFLAG_DESCENDXXX -offset indent +.It KTROP_SET Ta "Enable trace points specified in" +.Fa trpoints . +.It KTROP_CLEAR Ta "Disable trace points specified in" +.Fa trpoints . +.It KTROP_CLEARFILE Ta "Stop all tracing." +.It KTRFLAG_DESCEND Ta "The tracing change should apply to the" +specified process and all its current children. +.El +.Pp +The +.Fa trpoints +argument specifies the trace points of interest. +The defined trace points are: +.Bl -column KTRFAC_PROCCTORXXX -offset indent +.It KTRFAC_SYSCALL Ta "Trace system calls." +.It KTRFAC_SYSRET Ta "Trace return values from system calls." +.It KTRFAC_NAMEI Ta "Trace name lookup operations." +.It KTRFAC_GENIO Ta "Trace all I/O (note that this option can" +generate much output). +.It KTRFAC_PSIG Ta "Trace posted signals." +.It KTRFAC_CSW Ta "Trace context switch points." +.It KTRFAC_USER Ta "Trace application-specific events." +.It KTRFAC_STRUCT Ta "Trace certain data structures." +.It KTRFAC_SYSCTL Ta "Trace sysctls." +.It KTRFAC_PROCCTOR Ta "Trace process construction." +.It KTRFAC_PROCDTOR Ta "Trace process destruction." +.It KTRFAC_CAPFAIL Ta "Trace capability failures." +.It KTRFAC_FAULT Ta "Trace page faults." +.It KTRFAC_FAULTEND Ta "Trace the end of page faults." +.It KTRFAC_STRUCT_ARRAY Ta "Trace arrays of certain data structures." +.It KTRFAC_INHERIT Ta "Inherit tracing to future children." +.El +.Pp +Each tracing event outputs a record composed of a generic header +followed by a trace point specific structure. +The generic header is: +.Bd -literal +struct ktr_header { + int ktr_len; /* length of buf */ + short ktr_type; /* trace record type */ + pid_t ktr_pid; /* process id */ + char ktr_comm[MAXCOMLEN+1]; /* command name */ + struct timeval ktr_time; /* timestamp */ + long ktr_tid; /* thread id */ +}; +.Ed +.Pp +The +.Va ktr_len +field specifies the length of the +.Va ktr_type +data that follows this header. +The +.Va ktr_pid +and +.Va ktr_comm +fields specify the process and command generating the record. +The +.Va ktr_time +field gives the time (with microsecond resolution) +that the record was generated. +The +.Va ktr_tid +field holds a thread id. +.Pp +The generic header is followed by +.Va ktr_len +bytes of a +.Va ktr_type +record. +The type specific records are defined in the +.In sys/ktrace.h +include file. +.Sh SYSCTL TUNABLES +The following +.Xr sysctl 8 +tunables influence the behaviour of +.Fn ktrace : +.Bl -tag -width indent +.It Va kern.ktrace.genio_size +bounds the amount of data a traced I/O request will log +to the trace file. +.It Va kern.ktrace.request_pool +bounds the number of trace events being logged at a time. +.El +.Pp +Sysctl tunables that control process debuggability (as determined by +.Xr p_candebug 9 ) +also affect the operation of +.Fn ktrace . +.Sh RETURN VALUES +.Rv -std ktrace +.Sh ERRORS +The +.Fn ktrace +system call +will fail if: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named tracefile does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.It Bq Er ENOSYS +The kernel was not compiled with +.Nm +support. +.El +.Pp +A thread may be unable to log one or more tracing events due to a +temporary shortage of resources. +This condition is remembered by the kernel, and the next tracing request +that succeeds will have the flag +.Li KTR_DROP +set in its +.Va ktr_type +field. +.Sh SEE ALSO +.Xr kdump 1 , +.Xr ktrace 1 , +.Xr utrace 2 , +.Xr sysctl 8 , +.Xr p_candebug 9 +.Sh HISTORY +The +.Fn ktrace +system call first appeared in +.Bx 4.4 . diff --git a/lib/libsys/libc_stubs.c b/lib/libsys/libc_stubs.c new file mode 100644 index 000000000000..41d69a9355c3 --- /dev/null +++ b/lib/libsys/libc_stubs.c @@ -0,0 +1,11 @@ +/*- + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (c) 2024 SRI International + */ + +#define STUB_FUNC(f) \ + void (f)(void); \ + void (f)(void) { __builtin_trap(); } + +STUB_FUNC(elf_aux_info); diff --git a/lib/libsys/libsys.h b/lib/libsys/libsys.h new file mode 100644 index 000000000000..4ac7cfc14256 --- /dev/null +++ b/lib/libsys/libsys.h @@ -0,0 +1,25 @@ +/*- + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (c) 2024 SRI International + * + * This software was developed by SRI International, the University of + * Cambridge Computer Laboratory (Department of Computer Science and + * Technology), and Capabilities Limited under Defense Advanced Research + * Projects Agency (DARPA) Contract No. FA8750-24-C-B047 ("DEC"). + */ + +#ifndef _LIBSYS_H_ +#define _LIBSYS_H_ + +#include <sys/types.h> + +#include <_libsys.h> + +typedef int (__sys_syscall_t)(int number, ...); +typedef int (__sys___syscall_t)(int64_t number, ...); + +int __sys_syscall(int number, ...); +off_t __sys___syscall(int64_t number, ...); + +#endif /* _LIBSYS_H_ */ diff --git a/lib/libsys/libsys_sigwait.c b/lib/libsys/libsys_sigwait.c new file mode 100644 index 000000000000..ce1a416d76b3 --- /dev/null +++ b/lib/libsys/libsys_sigwait.c @@ -0,0 +1,45 @@ +/*- + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (c) 2010 davidxu@freebsd.org + * + * 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. + */ + +#include <errno.h> +#include <signal.h> +#include "libc_private.h" + +/* XXX: why does this symbol exist? */ +__weak_reference(__libsys_sigwait, __sigwait); + +int +__libsys_sigwait(const sigset_t *set, int *sig) +{ + int ret; + + /* POSIX does not allow EINTR to be returned */ + do { + ret = __sys_sigwait(set, sig); + } while (ret == EINTR); + return (ret); +} diff --git a/lib/libsys/link.2 b/lib/libsys/link.2 new file mode 100644 index 000000000000..e4122156678b --- /dev/null +++ b/lib/libsys/link.2 @@ -0,0 +1,316 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd March 30, 2021 +.Dt LINK 2 +.Os +.Sh NAME +.Nm link , +.Nm linkat +.Nd make a hard file link +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn link "const char *name1" "const char *name2" +.Ft int +.Fo linkat +.Fa "int fd1" "const char *name1" "int fd2" "const char *name2" "int flag" +.Fc +.Sh DESCRIPTION +The +.Fn link +system call +atomically creates the specified directory entry (hard link) +.Fa name2 +with the attributes of the underlying object pointed at by +.Fa name1 . +If the link is successful: the link count of the underlying object +is incremented; +.Fa name1 +and +.Fa name2 +share equal access and rights +to the +underlying object. +.Pp +If +.Fa name1 +is removed, the file +.Fa name2 +is not deleted and the link count of the +underlying object is +decremented. +.Pp +The object pointed at by the +.Fa name1 +argument +must exist for the hard link to +succeed and +both +.Fa name1 +and +.Fa name2 +must be in the same file system. +The +.Fa name1 +argument +may not be a directory. +.Pp +The +.Fn linkat +system call is equivalent to +.Fa link +except in the case where either +.Fa name1 +or +.Fa name2 +or both are relative paths. +In this case a relative path +.Fa name1 +is interpreted relative to +the directory associated with the file descriptor +.Fa fd1 +instead of the current working directory and similarly for +.Fa name2 +and the file descriptor +.Fa fd2 . +.Pp +Values for +.Fa flag +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.In fcntl.h : +.Bl -tag -width indent +.It Dv AT_SYMLINK_FOLLOW +If +.Fa name1 +names a symbolic link, a new link for the target of the symbolic link is +created. +.It Dv AT_RESOLVE_BENEATH +Only walk paths below the directory specified by the +.Ar fd1 +descriptor. +See the description of the +.Dv O_RESOLVE_BENEATH +flag in the +.Xr open 2 +manual page. +.It Dv AT_EMPTY_PATH +If the +.Fa name1 +argument is an empty string, link the file referenced by the descriptor +.Fa fd1 . +The operation requires that the calling process has the +.Dv PRIV_VFS_FHOPEN +privilege, effectively being executed with effective user +.Dv root . +.El +.Pp +If +.Fn linkat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd1 +or +.Fa fd2 +parameter, the current working directory is used for the respective +.Fa name +argument. +If both +.Fa fd1 +and +.Fa fd2 +have value +.Dv AT_FDCWD , +the behavior is identical to a call to +.Fn link . +Unless +.Fa flag +contains the +.Dv AT_SYMLINK_FOLLOW +flag, if +.Fa name1 +names a symbolic link, a new link is created for the symbolic link +.Fa name1 +and not its target. +.Sh RETURN VALUES +.Rv -std link +.Sh ERRORS +The +.Fn link +system call +will fail and no link will be created if: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of either path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of either pathname exceeded 255 characters, +or entire length of either path name exceeded 1023 characters. +.It Bq Er ENOENT +A component of either path prefix does not exist. +.It Bq Er EOPNOTSUPP +The file system containing the file named by +.Fa name1 +does not support links. +.It Bq Er EMLINK +The link count of the file named by +.Fa name1 +would exceed 32767. +.It Bq Er EACCES +A component of either path prefix denies search permission. +.It Bq Er EACCES +The requested link requires writing in a directory with a mode +that denies write permission. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating one of the pathnames. +.It Bq Er ENOENT +The file named by +.Fa name1 +does not exist. +.It Bq Er EEXIST +The link named by +.Fa name2 +does exist. +.It Bq Er EPERM +The file named by +.Fa name1 +is a directory. +.It Bq Er EPERM +The file named by +.Fa name1 +has its immutable or append-only flag set, see the +.Xr chflags 2 +manual page for more information. +.It Bq Er EPERM +The parent directory of the file named by +.Fa name2 +has its immutable flag set. +.It Bq Er EXDEV +The link named by +.Fa name2 +and the file named by +.Fa name1 +are on different file systems. +.It Bq Er ENOSPC +The directory in which the entry for the new link is being placed +cannot be extended because there is no space left on the file +system containing the directory. +.It Bq Er EDQUOT +The directory in which the entry for the new link +is being placed cannot be extended because the +user's quota of disk blocks on the file system +containing the directory has been exhausted. +.It Bq Er EIO +An I/O error occurred while reading from or writing to +the file system to make the directory entry. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.It Bq Er EROFS +The requested link requires writing in a directory on a read-only file +system. +.It Bq Er EFAULT +One of the pathnames specified +is outside the process's allocated address space. +.El +.Pp +In addition to the errors returned by the +.Fn link , +the +.Fn linkat +system call may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa name1 +or +.Fa name2 +argument does not specify an absolute path and the +.Fa fd1 +or +.Fa fd2 +argument, respectively, is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er EINVAL +The value of the +.Fa flag +argument is not valid. +.It Bq Er ENOTDIR +The +.Fa name1 +or +.Fa name2 +argument is not an absolute path and +.Fa fd1 +or +.Fa fd2 , +respectively, is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.It Bq Er ENOTCAPABLE +.Fa name1 +is not strictly relative to the starting directory. +For example, +.Fa name1 +is absolute or includes a ".." component that escapes +the directory hierarchy specified by +.Fa fd , +and the process is in capability mode or the +.Dv AT_RESOLVE_BENEATH +flag was specified. +.El +.Sh SEE ALSO +.Xr chflags 2 , +.Xr readlink 2 , +.Xr symlink 2 , +.Xr unlink 2 +.Sh STANDARDS +The +.Fn link +system call is expected to conform to +.St -p1003.1-90 . +The +.Fn linkat +system call follows The Open Group Extended API Set 2 specification. +.Sh HISTORY +The +.Fn link +function appeared in +.At v1 . +The +.Fn linkat +system call appeared in +.Fx 8.0 . +.Pp +The +.Fn link +system call traditionally allows the super-user to link directories which +corrupts the file system coherency. +This implementation no longer permits it. diff --git a/lib/libsys/lio_listio.2 b/lib/libsys/lio_listio.2 new file mode 100644 index 000000000000..bda65c38b1ac --- /dev/null +++ b/lib/libsys/lio_listio.2 @@ -0,0 +1,248 @@ +.\" Copyright (c) 2003 Tim J. Robbins +.\" All rights reserved. +.\" +.\" 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. +.\" +.Dd January 13, 2024 +.Dt LIO_LISTIO 2 +.Os +.Sh NAME +.Nm lio_listio +.Nd "list directed I/O (REALTIME)" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In aio.h +.Ft int +.Fo lio_listio +.Fa "int mode" +.Fa "struct aiocb * const list[]" +.Fa "int nent" +.Fa "struct sigevent *sig" +.Fc +.Sh DESCRIPTION +The +.Fn lio_listio +function initiates a list of I/O requests with a single function call. +The +.Fa list +argument is an array of pointers to +.Vt aiocb +structures describing each operation to perform, +with +.Fa nent +elements. +.Dv NULL +elements are ignored. +.Pp +The +.Va aio_lio_opcode +field of each +.Vt aiocb +specifies the operation to be performed. +The following operations are supported: +.Bl -tag -width ".Dv LIO_WRITE" +.It Dv LIO_READ +Read data as if by a call to +.Xr aio_read 2 . +.It Dv LIO_READV +Read data as if by a call to +.Xr aio_readv 2 . +.It Dv LIO_NOP +No operation. +.It Dv LIO_WRITE +Write data as if by a call to +.Xr aio_write 2 . +.It Dv LIO_WRITEV +Write data as if by a call to +.Xr aio_writev 2 . +.El +.Pp +If the +.Dv LIO_READ , +.Dv LIO_READV , +.Dv LIO_WRITE , +.Dv LIO_WRITEV +opcodes are or-ed with the +.Dv LIO_FOFFSET +flag, the corresponding read or write operation uses the current file +descriptor offset instead of +.Va aio_offset +from +.Vt aiocb . +.Pp +If the +.Fa mode +argument is +.Dv LIO_WAIT , +.Fn lio_listio +does not return until all the requested operations have been completed. +If +.Fa mode +is +.Dv LIO_NOWAIT , +.Fa sig +can be used to request asynchronous notification when all operations have +completed. +If +.Fa sig +is +.Dv NULL , +no notification is sent. +.Pp +For +.Dv SIGEV_KEVENT +notifications, +the posted kevent will contain: +.Bl -column ".Va filter" +.It Sy Member Ta Sy Value +.It Va ident Ta Fa list +.It Va filter Ta Dv EVFILT_LIO +.It Va udata Ta +value stored in +.Fa sig->sigev_value +.El +.Pp +For +.Dv SIGEV_SIGNO +and +.Dv SIGEV_THREAD_ID +notifications, +the information for the queued signal will include +.Dv SI_ASYNCIO +in the +.Va si_code +field and the value stored in +.Fa sig->sigev_value +in the +.Va si_value +field. +.Pp +For +.Dv SIGEV_THREAD +notifications, +the value stored in +.Fa sig->sigev_value +is passed to the +.Fa sig->sigev_notify_function +as described in +.Xr sigevent 3 . +.Pp +The order in which the requests are carried out is not specified; +in particular, there is no guarantee that they will be executed in +the order 0, 1, ..., +.Fa nent Ns \-1 . +.Sh RETURN VALUES +If +.Fa mode +is +.Dv LIO_WAIT , +the +.Fn lio_listio +function returns 0 if the operations completed successfully, +otherwise \-1. +.Pp +If +.Fa mode +is +.Dv LIO_NOWAIT , +the +.Fn lio_listio +function returns 0 if the operations are successfully queued, +otherwise \-1. +.Sh ERRORS +The +.Fn lio_listio +function will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +There are not enough resources to enqueue the requests. +.It Bq Er EAGAIN +The request would cause the system-wide limit +.Dv {AIO_MAX} +to be exceeded. +.It Bq Er EINVAL +The +.Fa mode +argument is neither +.Dv LIO_WAIT +nor +.Dv LIO_NOWAIT , +or +.Fa nent +is greater than +.Dv {AIO_LISTIO_MAX} . +.It Bq Er EINVAL +The asynchronous notification method in +.Fa sig->sigev_notify +is invalid or not supported. +.It Bq Er EINTR +A signal interrupted the system call before it could be completed. +.It Bq Er EIO +One or more requests failed. +.El +.Pp +In addition, the +.Fn lio_listio +function may fail for any of the reasons listed for +.Xr aio_read 2 +and +.Xr aio_write 2 . +.Pp +If +.Fn lio_listio +succeeds, or fails with an error code of +.Er EAGAIN , EINTR , +or +.Er EIO , +some of the requests may have been initiated. +The caller should check the error status of each +.Vt aiocb +structure individually by calling +.Xr aio_error 2 . +.Sh SEE ALSO +.Xr aio_error 2 , +.Xr aio_read 2 , +.Xr aio_readv 2 , +.Xr aio_write 2 , +.Xr aio_writev 2 , +.Xr read 2 , +.Xr write 2 , +.Xr sigevent 3 , +.Xr siginfo 3 , +.Xr aio 4 +.Sh STANDARDS +The +.Fn lio_listio +function is expected to conform to +.St -p1003.1-2001 . +The +.Dv LIO_READV +and +.Dv LIO_WRITEV +operations are +.Fx extensions, and should not be used in portable code. +.Sh HISTORY +The +.Fn lio_listio +system call first appeared in +.Fx 3.0 . diff --git a/lib/libsys/listen.2 b/lib/libsys/listen.2 new file mode 100644 index 000000000000..984da2552862 --- /dev/null +++ b/lib/libsys/listen.2 @@ -0,0 +1,201 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd April 30, 2023 +.Dt LISTEN 2 +.Os +.Sh NAME +.Nm listen +.Nd listen for connections on a socket +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/socket.h +.Ft int +.Fn listen "int s" "int backlog" +.Sh DESCRIPTION +To accept connections, a socket +is first created with +.Xr socket 2 , +a willingness to accept incoming connections and +a queue limit for incoming connections are specified with +.Fn listen , +and then the connections are +accepted with +.Xr accept 2 . +The +.Fn listen +system call applies only to sockets of type +.Dv SOCK_STREAM +or +.Dv SOCK_SEQPACKET . +.Pp +The +.Fa backlog +argument defines the maximum length the queue of +pending connections may grow to. +The real maximum queue length will be 1.5 times more than the value +specified in the +.Fa backlog +argument. +A subsequent +.Fn listen +system call on the listening socket allows the caller to change the maximum +queue length using a new +.Fa backlog +argument. +If a connection +request arrives with the queue full the client may +receive an error with an indication of +.Er ECONNREFUSED , +or, in the case of TCP, the connection will be +silently dropped. +.Pp +Current queue lengths of listening sockets can be queried using +.Xr netstat 1 +command. +.Pp +Note that before +.Fx 4.5 +and the introduction of the syncache, +the +.Fa backlog +argument also determined the length of the incomplete +connection queue, which held TCP sockets in the process +of completing TCP's 3-way handshake. +These incomplete connections +are now held entirely in the syncache, which is unaffected by +queue lengths. +Inflated +.Fa backlog +values to help handle denial +of service attacks are no longer necessary. +.Pp +The +.Xr sysctl 3 +MIB variable +.Va kern.ipc.soacceptqueue +specifies a hard limit on +.Fa backlog ; +if a value greater than +.Va kern.ipc.soacceptqueue +or less than zero is specified, +.Fa backlog +is silently forced to +.Va kern.ipc.soacceptqueue . +.Pp +If the listen queue overflows, the kernel will emit a syslog message +using default priority LOG_DEBUG (7). +The +.Xr sysctl 3 +MIB variable +.Va kern.ipc.sooverprio +may be used to change this priority to any value in a range of 0..7 +(LOG_EMERG..LOG_DEBUG). +See +.Xr syslog 3 +for details. +It may be set to -1 to disable these messages. +.Pp +The variable +.Va kern.ipc.sooverinterval +specifies a per-socket limit on how often the kernel will emit these messages. +.Sh INTERACTION WITH ACCEPT FILTERS +When accept filtering is used on a socket, a second queue will +be used to hold sockets that have connected, but have not yet +met their accept filtering criteria. +Once the criteria has been +met, these sockets will be moved over into the completed connection +queue to be +.Xr accept 2 Ns ed . +If this secondary queue is full and a +new connection comes in, the oldest socket which has not yet met +its accept filter criteria will be terminated. +.Pp +This secondary queue, like the primary listen queue, is sized +according to the +.Fa backlog +argument. +.Sh RETURN VALUES +.Rv -std listen +.Sh ERRORS +The +.Fn listen +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The argument +.Fa s +is not a valid descriptor. +.It Bq Er EDESTADDRREQ +The socket is not bound to a local address, and the protocol does not +support listening on an unbound socket. +.It Bq Er EINVAL +The socket is already connected, or in the process of being connected. +.It Bq Er ENOTSOCK +The argument +.Fa s +is not a socket. +.It Bq Er EOPNOTSUPP +The socket is not of a type that supports the operation +.Fn listen . +.El +.Sh SEE ALSO +.Xr netstat 1 , +.Xr accept 2 , +.Xr connect 2 , +.Xr socket 2 , +.Xr sysctl 3 , +.Xr syslog 3 , +.Xr sysctl 8 , +.Xr accept_filter 9 +.Sh HISTORY +The +.Fn listen +system call appeared in +.Bx 4.2 . +The ability to configure the maximum +.Fa backlog +at run-time, and to use a negative +.Fa backlog +to request the maximum allowable value, was introduced in +.Fx 2.2 . +The +.Va kern.ipc.somaxconn +.Xr sysctl 3 +has been replaced with +.Va kern.ipc.soacceptqueue +in +.Fx 10.0 +to prevent confusion about its actual functionality. +The original +.Xr sysctl 3 +.Va kern.ipc.somaxconn +is still available but hidden from a +.Xr sysctl 3 +-a output so that existing applications and scripts continue to work. diff --git a/lib/libsys/lockf.3 b/lib/libsys/lockf.3 new file mode 100644 index 000000000000..bfd5719dee11 --- /dev/null +++ b/lib/libsys/lockf.3 @@ -0,0 +1,264 @@ +.\" $NetBSD: lockf.3,v 1.10 2008/04/30 13:10:50 martin Exp $ +.\" +.\" Copyright (c) 1997 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Klaus Klein and S.P. Zeidler. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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. +.\" +.Dd September 11, 2013 +.Dt LOCKF 3 +.Os +.Sh NAME +.Nm lockf +.Nd record locking on files +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn lockf "int fd" "int function" "off_t size" +.Sh DESCRIPTION +The +.Fn lockf +function allows sections of a file to be locked with advisory-mode locks. +Calls to +.Fn lockf +from other processes which attempt to lock the locked file section will +either return an error value or block until the section becomes unlocked. +All the locks for a process are removed when the process terminates. +.Pp +The argument +.Fa fd +is an open file descriptor. +The file descriptor must have been opened either for write-only +.Dv ( O_WRONLY ) +or read/write +.Dv ( O_RDWR ) +operation. +.Pp +The +.Fa function +argument is a control value which specifies the action to be taken. +The permissible values for +.Fa function +are as follows: +.Bl -tag -width F_ULOCKXX -compact -offset indent +.It Sy Function +.Sy Description +.It Dv F_ULOCK +unlock locked sections +.It Dv F_LOCK +lock a section for exclusive use +.It Dv F_TLOCK +test and lock a section for exclusive use +.It Dv F_TEST +test a section for locks by other processes +.El +.Pp +.Dv F_ULOCK +removes locks from a section of the file; +.Dv F_LOCK +and +.Dv F_TLOCK +both lock a section of a file if the section is available; +.Dv F_TEST +detects if a lock by another process is present on the specified section. +.Pp +The +.Fa size +argument is the number of contiguous bytes to be locked or +unlocked. +The section to be locked or unlocked starts at the current +offset in the file and extends forward for a positive size or backward +for a negative size (the preceding bytes up to but not including the +current offset). +However, it is not permitted to lock a section that +starts or extends before the beginning of the file. +If +.Fa size +is 0, the section from the current offset through the largest possible +file offset is locked (that is, from the current offset through the +present or any future end-of-file). +.Pp +The sections locked with +.Dv F_LOCK +or +.Dv F_TLOCK +may, in whole or in part, contain or be contained by a previously +locked section for the same process. +When this occurs, or if adjacent +locked sections would occur, the sections are combined into a single +locked section. +If the request would cause the number of locks to +exceed a system-imposed limit, the request will fail. +.Pp +.Dv F_LOCK +and +.Dv F_TLOCK +requests differ only by the action taken if the section is not +available. +.Dv F_LOCK +blocks the calling process until the section is available. +.Dv F_TLOCK +makes the function fail if the section is already locked by another +process. +.Pp +File locks are released on first close by the locking process of any +file descriptor for the file. +.Pp +.Dv F_ULOCK +requests release (wholly or in part) one or more locked sections +controlled by the process. +Locked sections will be unlocked starting +at the current file offset through +.Fa size +bytes or to the end of file if size is 0. +When all of a locked section +is not released (that is, when the beginning or end of the area to be +unlocked falls within a locked section), the remaining portions of +that section are still locked by the process. +Releasing the center +portion of a locked section will cause the remaining locked beginning +and end portions to become two separate locked sections. +If the +request would cause the number of locks in the system to exceed a +system-imposed limit, the request will fail. +.Pp +An +.Dv F_ULOCK +request in which size is non-zero and the offset of the last byte of +the requested section is the maximum value for an object of type +off_t, when the process has an existing lock in which size is 0 and +which includes the last byte of the requested section, will be treated +as a request to unlock from the start of the requested section with a +size equal to 0. +Otherwise an +.Dv F_ULOCK +request will attempt to unlock only the requested section. +.Pp +A potential for deadlock occurs if a process controlling a locked +region is put to sleep by attempting to lock the locked region of +another process. +This implementation detects that sleeping until a +locked region is unlocked would cause a deadlock and fails with an +.Er EDEADLK +error. +.Pp +The +.Fn lockf , +.Xr fcntl 2 , +and +.Xr flock 2 +locks are compatible. +Processes using different locking interfaces can cooperate +over the same file safely. +However, only one of such interfaces should be used within +the same process. +If a file is locked by a process through +.Xr flock 2 , +any record within the file will be seen as locked +from the viewpoint of another process using +.Xr fcntl 2 +or +.Fn lockf , +and vice versa. +.Pp +Blocking on a section is interrupted by any signal. +.Sh RETURN VALUES +.Rv -std lockf +In the case of a failure, existing locks are not changed. +.Sh ERRORS +The +.Fn lockf +function +will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The argument +.Fa function +is +.Dv F_TLOCK +or +.Dv F_TEST +and the section is already locked by another process. +.It Bq Er EBADF +The argument +.Fa fd +is not a valid open file descriptor. +.Pp +The argument +.Fa function +is +.Dv F_LOCK +or +.Dv F_TLOCK , +and +.Fa fd +is not a valid file descriptor open for writing. +.It Bq Er EDEADLK +The argument +.Fa function +is +.Dv F_LOCK +and a deadlock is detected. +.It Bq Er EINTR +The argument +.Fa function +is F_LOCK +and +.Fn lockf +was interrupted by the delivery of a signal. +.It Bq Er EINVAL +The argument +.Fa function +is not one of +.Dv F_ULOCK , +.Dv F_LOCK , +.Dv F_TLOCK +or +.Dv F_TEST . +.Pp +The argument +.Fa fd +refers to a file that does not support locking. +.It Bq Er ENOLCK +The argument +.Fa function +is +.Dv F_ULOCK , +.Dv F_LOCK +or +.Dv F_TLOCK , +and satisfying the lock or unlock request would result in the number +of locked regions in the system exceeding a system-imposed limit. +.El +.Sh SEE ALSO +.Xr fcntl 2 , +.Xr flock 2 +.Sh STANDARDS +The +.Fn lockf +function conforms to +.St -xpg4.2 . diff --git a/lib/libsys/lseek.2 b/lib/libsys/lseek.2 new file mode 100644 index 000000000000..6df543d8ce72 --- /dev/null +++ b/lib/libsys/lseek.2 @@ -0,0 +1,243 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd July 13, 2020 +.Dt LSEEK 2 +.Os +.Sh NAME +.Nm lseek +.Nd reposition read/write file offset +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft off_t +.Fn lseek "int fildes" "off_t offset" "int whence" +.Sh DESCRIPTION +The +.Fn lseek +system call repositions the offset of the file descriptor +.Fa fildes +to the +argument +.Fa offset +according to the directive +.Fa whence . +The argument +.Fa fildes +must be an open +file descriptor. +The +.Fn lseek +system call +repositions the file position pointer associated with the file +descriptor +.Fa fildes +as follows: +.Bl -item -offset indent +.It +If +.Fa whence +is +.Dv SEEK_SET , +the offset is set to +.Fa offset +bytes. +.It +If +.Fa whence +is +.Dv SEEK_CUR , +the offset is set to its current location plus +.Fa offset +bytes. +.It +If +.Fa whence +is +.Dv SEEK_END , +the offset is set to the size of the +file plus +.Fa offset +bytes. +.It +If +.Fa whence +is +.Dv SEEK_HOLE , +the offset is set to the start of the next hole greater than or equal +to the supplied +.Fa offset . +The definition of a hole is provided below. +.It +If +.Fa whence +is +.Dv SEEK_DATA , +the offset is set to the start of the next non-hole file region greater +than or equal to the supplied +.Fa offset . +.El +.Pp +The +.Fn lseek +system call allows the file offset to be set beyond the end +of the existing end-of-file of the file. +If data is later written +at this point, subsequent reads of the data in the gap return +bytes of zeros (until data is actually written into the gap). +However, the +.Fn lseek +system call does not, by itself, extend the size of a file. +.Pp +A +.Qq hole +is defined as a contiguous range of bytes in a file, all having the value of +zero, but not all zeros in a file are guaranteed to be represented as holes +returned with +.Dv SEEK_HOLE . +File systems are allowed to expose ranges of zeros with +.Dv SEEK_HOLE , +but not required to. +Applications can use +.Dv SEEK_HOLE +to optimise their behavior for ranges of zeros, but must not depend on it to +find all such ranges in a file. +Each file is presented as having a zero-size virtual hole at the very +end of the file. +The existence of a hole at the end of every data region allows for easy +programming and also provides compatibility to the original implementation +in Solaris. +It also causes the current file size (i.e., end-of-file offset) to be returned +to indicate that there are no more holes past the supplied +.Fa offset . +Applications should use +.Fn fpathconf _PC_MIN_HOLE_SIZE +or +.Fn pathconf _PC_MIN_HOLE_SIZE +to determine if a file system supports +.Dv SEEK_HOLE . +See +.Xr pathconf 2 . +.Pp +For file systems that do not supply information about holes, the file will be +represented as one entire data region. +.Sh RETURN VALUES +Upon successful completion, +.Fn lseek +returns the resulting offset location as measured in bytes from the +beginning of the file. +Otherwise, +a value of -1 is returned and +.Va errno +is set to indicate +the error. +.Sh ERRORS +The +.Fn lseek +system call +will fail and the file position pointer will remain unchanged if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fildes +argument +is not an open file descriptor. +.It Bq Er EINVAL +The +.Fa whence +argument +is not a proper value +or the resulting file offset would +be negative for a non-character special file. +.It Bq Er ENXIO +For +.Dv SEEK_DATA , +there are no more data regions past the supplied offset. +Due to existence of the hole at the end of the file, for +.Dv SEEK_HOLE +this error is only returned when the +.Fa offset +already points to the end-of-file position. +.It Bq Er EOVERFLOW +The resulting file offset would be a value which cannot be represented +correctly in an object of type +.Fa off_t . +.It Bq Er ESPIPE +The +.Fa fildes +argument +is associated with a pipe, socket, or FIFO. +.El +.Sh SEE ALSO +.Xr dup 2 , +.Xr open 2 , +.Xr pathconf 2 +.Sh STANDARDS +The +.Fn lseek +system call is expected to conform to +.St -p1003.1-2008 . +.Pp +The +.Dv SEEK_HOLE +and +.Dv SEEK_DATA +directives, along with the +.Er ENXIO +error, are extensions to that specification. +.Sh HISTORY +The +.Fn lseek +function appeared in +.At v7 . +.Sh BUGS +If the +.Fn lseek +system call is operating on a device which is incapable of seeking, +it will request the seek operation and return successfully, +even though no seek was performed. +Because the +.Ar offset +argument will be stored unconditionally in the file descriptor of that device, +there is no way to confirm if the seek operation succeeded or not +(e.g. using the +.Fn ftell +function). +Device types which are known to be incapable of seeking include +tape drives. +.Pp +The +.Fn lseek +system call will not detect whether media are present in changeable +media devices such as DVD or Blu-ray devices. +A requested seek operation will therefore return sucessfully when no +medium is present. +.Pp +This document's use of +.Fa whence +is incorrect English, but is maintained for historical reasons. diff --git a/lib/libsys/madvise.2 b/lib/libsys/madvise.2 new file mode 100644 index 000000000000..9a6e34416012 --- /dev/null +++ b/lib/libsys/madvise.2 @@ -0,0 +1,183 @@ +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd July 12, 2015 +.Dt MADVISE 2 +.Os +.Sh NAME +.Nm madvise , posix_madvise +.Nd give advice about use of memory +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/mman.h +.Ft int +.Fn madvise "void *addr" "size_t len" "int behav" +.Ft int +.Fn posix_madvise "void *addr" "size_t len" "int behav" +.Sh DESCRIPTION +The +.Fn madvise +system call +allows a process that has knowledge of its memory behavior +to describe it to the system. +The +.Fn posix_madvise +interface is identical, except it returns an error number on error and does +not modify +.Va errno , +and is provided for standards conformance. +.Pp +The known behaviors are: +.Bl -tag -width MADV_SEQUENTIAL +.It Dv MADV_NORMAL +Tells the system to revert to the default paging +behavior. +.It Dv MADV_RANDOM +Is a hint that pages will be accessed randomly, and prefetching +is likely not advantageous. +.It Dv MADV_SEQUENTIAL +Causes the VM system to depress the priority of +pages immediately preceding a given page when it is faulted in. +.It Dv MADV_WILLNEED +Causes pages that are in a given virtual address range +to temporarily have higher priority, and if they are in +memory, decrease the likelihood of them being freed. +Additionally, +the pages that are already in memory will be immediately mapped into +the process, thereby eliminating unnecessary overhead of going through +the entire process of faulting the pages in. +This WILL NOT fault +pages in from backing store, but quickly map the pages already in memory +into the calling process. +.It Dv MADV_DONTNEED +Allows the VM system to decrease the in-memory priority +of pages in the specified address range. +Consequently, future references to this address range are more likely +to incur a page fault. +.It Dv MADV_FREE +Gives the VM system the freedom to free pages, +and tells the system that information in the specified page range +is no longer important. +This is an efficient way of allowing +.Xr malloc 3 +to free pages anywhere in the address space, while keeping the address space +valid. +The next time that the page is referenced, the page might be demand +zeroed, or might contain the data that was there before the +.Dv MADV_FREE +call. +References made to that address space range will not make the VM system +page the information back in from backing store until the page is +modified again. +.It Dv MADV_NOSYNC +Request that the system not flush the data associated with this map to +physical backing store unless it needs to. +Typically this prevents the +file system update daemon from gratuitously writing pages dirtied +by the VM system to physical disk. +Note that VM/file system coherency is +always maintained, this feature simply ensures that the mapped data is +only flush when it needs to be, usually by the system pager. +.Pp +This feature is typically used when you want to use a file-backed shared +memory area to communicate between processes (IPC) and do not particularly +need the data being stored in that area to be physically written to disk. +With this feature you get the equivalent performance with mmap that you +would expect to get with SysV shared memory calls, but in a more controllable +and less restrictive manner. +However, note that this feature is not portable +across UNIX platforms (though some may do the right thing by default). +For more information see the MAP_NOSYNC section of +.Xr mmap 2 +.It Dv MADV_AUTOSYNC +Undoes the effects of MADV_NOSYNC for any future pages dirtied within the +address range. +The effect on pages already dirtied is indeterminate - they +may or may not be reverted. +You can guarantee reversion by using the +.Xr msync 2 +or +.Xr fsync 2 +system calls. +.It Dv MADV_NOCORE +Region is not included in a core file. +.It Dv MADV_CORE +Include region in a core file. +.It Dv MADV_PROTECT +Informs the VM system this process should not be killed when the +swap space is exhausted. +The process must have superuser privileges. +This should be used judiciously in processes that must remain running +for the system to properly function. +.El +.Pp +Portable programs that call the +.Fn posix_madvise +interface should use the aliases +.Dv POSIX_MADV_NORMAL , POSIX_MADV_SEQUENTIAL , +.Dv POSIX_MADV_RANDOM , POSIX_MADV_WILLNEED , +and +.Dv POSIX_MADV_DONTNEED +rather than the flags described above. +.Sh RETURN VALUES +.Rv -std madvise +.Sh ERRORS +The +.Fn madvise +system call will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa behav +argument is not valid. +.It Bq Er ENOMEM +The virtual address range specified by the +.Fa addr +and +.Fa len +arguments is not valid. +.It Bq Er EPERM +.Dv MADV_PROTECT +was specified and the process does not have superuser privileges. +.El +.Sh SEE ALSO +.Xr mincore 2 , +.Xr mprotect 2 , +.Xr msync 2 , +.Xr munmap 2 , +.Xr posix_fadvise 2 +.Sh STANDARDS +The +.Fn posix_madvise +interface conforms to +.St -p1003.1-2001 . +.Sh HISTORY +The +.Fn madvise +system call first appeared in +.Bx 4.4 . diff --git a/lib/libsys/membarrier.2 b/lib/libsys/membarrier.2 new file mode 100644 index 000000000000..87db620975ef --- /dev/null +++ b/lib/libsys/membarrier.2 @@ -0,0 +1,151 @@ +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2024 The FreeBSD Foundation +.\" +.\" This documentation was written by Ed Maste <emaste@FreeBSD.org> +.\" under sponsorship from the FreeBSD Foundation. +.\" +.\" 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 AUTHORS 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 AUTHORS 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. +.\" +.Dd October 6, 2024 +.Dt MEMBARRIER 2 +.Os +.Sh NAME +.Nm membarrier +.Nd memory barrier +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/membarrier.h +.Ft int +.Fn membarrier "int cmd" "unsigned flags" "int cpu_id" +.Sh DESCRIPTION +The +.Nm +system call provides a memory barrier, ensuring ordering between memory +accesses performed by different threads or processes within the same address +space. +.Pp +The following values for +.Fa cmd +may be specified: +.Bl -tag -width Dv +.It Dv MEMBARRIER_CMD_QUERY +Query supported commands. +A bitmask of commands supported by the kernel is returned. +.It Dv MEMBARRIER_CMD_GLOBAL +Issue a memory barrier for all threads from all processes. +.It Dv MEMBARRIER_CMD_SHARED +This is an alias for +.Dv MEMBARRIER_CMD_GLOBAL . +.It Dv MEMBARRIER_CMD_GLOBAL_EXPEDITED +Execute a memory barrier on all running threads of all processes registered +with +.Dv MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED . +.It Dv MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED +Register the process to receive +.Dv MEMBARRIER_CMD_GLOBAL_EXPEDITED +memory barriers. +.It Dv MEMBARRIER_CMD_PRIVATE_EXPEDITED +Execute a memory barrier on each running thread belonging to the same process +as the thread calling +.Nm . +.It Dv MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED +Register the process to receive +.Dv MEMBARRIER_CMD_PRIVATE_EXPEDITED +memory barriers. +.It Dv MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE +In addition to the guarantees provided by +.Dv MEMBARRIER_CMD_PRIVATE_EXPEDITED +it also executes machine-specific serialization instructions, which +ensures that all possible speculative and out-of-order activities on the target +CPU are fenced. +.It Dv MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_SYNC_CORE +Register the process to receive +.Dv MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE +memory barriers. +.El +.Pp +The following +.Fa cmd +values are defined for source compatibility but are not yet supported: +.Pp +.Bl -tag -width Dv -compact +.It Dv MEMBARRIER_CMD_PRIVATE_EXPEDITED_RSEQ +.It Dv MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_RSEQ +.El +.Pp +The +.Fa flags +argument must be 0. +The +.Fa cpu_id +argument is ignored. +.Sh RETURN VALUES +If the +.Fa cmd +is +.Dv MEMBARRIER_CMD_QUERY +a bitmask of supported commands is returned. +Otherwise, on success, +.Nm +returns 0. +On error, -1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +.Nm +may fail with the following errors: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa cmd +does not specify a valid command. +.It Bq Er EINVAL +.Fa flags +is not 0. +.It Bq Er EPERM +An attempt was made to use +.Dv MEMBARRIER_CMD_GLOBAL_EXPEDITED , +.Dv MEMBARRIER_CMD_PRIVATE_EXPEDITED , +or +.Dv MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE +by a process that did not previously register use with the corresponding +.Dv MEMBARRIER_CMD_REGISTER_* +.Fa cmd . +.El +.\" .Sh SEE ALSO +.Sh STANDARDS +The +.Nm +system call originated in Linux. +This implementation aims to be source-compatible with the Linux implementation. +Certain +.Fa cmd +and +.Fa flags +values are currently not supported by +.Fx . +.Sh HISTORY +The +.Nm +function was introduced in +.Fx 14.1 . diff --git a/lib/libsys/mincore.2 b/lib/libsys/mincore.2 new file mode 100644 index 000000000000..0cb77d9937ce --- /dev/null +++ b/lib/libsys/mincore.2 @@ -0,0 +1,149 @@ +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd August 23, 2020 +.Dt MINCORE 2 +.Os +.Sh NAME +.Nm mincore +.Nd determine residency of memory pages +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/mman.h +.Ft int +.Fn mincore "const void *addr" "size_t len" "char *vec" +.Sh DESCRIPTION +The +.Fn mincore +system call determines whether each of the pages in the region beginning at +.Fa addr +and continuing for +.Fa len +bytes is resident or mapped, depending on the value of sysctl +.Va vm.mincore_mapped . +.\"The beginning address, +.\".Fa addr , +.\"is first rounded down to a multiple of the page size (see +.\".Xr getpagesize 3 ) . +.\"The end address, +.\".Fa addr No + Fa len , +.\"is rounded up to a multiple of the page size. +The status is returned in the +.Fa vec +array, one character per page. +Each character is either 0 if the page is not resident, or a combination of +the following flags (defined in +.In sys/mman.h ) : +.Bl -tag -width ".Dv MINCORE_REFERENCED_OTHER" +.It Dv MINCORE_INCORE +Page is in core (resident). +.It Dv MINCORE_REFERENCED +Page has been referenced by us. +.It Dv MINCORE_MODIFIED +Page has been modified by us. +.It Dv MINCORE_REFERENCED_OTHER +Page has been referenced. +.It Dv MINCORE_MODIFIED_OTHER +Page has been modified. +.It Dv MINCORE_PSIND(i) +Page is part of a large +.Pq Dq super +page with size given by index +.Dv i +in the array returned by +.Xr getpagesizes 3 . +.It Dv MINCORE_SUPER +A mask of the valid +.Dv MINCORE_PSIND() +values. +If any bits in this mask are set, the page is part of a large +.Pq Dq super +page. +.El +.Pp +The information returned by +.Fn mincore +may be out of date by the time the system call returns. +The only way to ensure that a page is resident is to lock it into memory +with the +.Xr mlock 2 +system call. +.Pp +If the +.Va vm.mincore_mapped +sysctl is set to a non-zero value (default), only the current process' +mappings of the pages in the specified virtual address range are examined. +This does not preclude the system from returning +.Dv MINCORE_REFERENCED_OTHER +and +.Dv MINCORE_MODIFIED_OTHER +statuses. +Otherwise, if the sysctl value is zero, all resident pages backing the +specified address range are examined, regardless of the mapping state. +.Sh IMPLEMENTATION NOTES +Prior to the introduction of +.Dv MINCORE_PSIND() +in +.Fx 13.0 , +.Dv MINCORE_SUPER +consisted of a single bit equal to +.Dv MINCORE_PSIND(1) . +In particular, applications compiled using the old value of +.Dv MINCORE_SUPER +will not identify large pages with size index 2 as being large pages. +.Sh RETURN VALUES +.Rv -std mincore +.Sh ERRORS +The +.Fn mincore +system call will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +The virtual address range specified by the +.Fa addr +and +.Fa len +arguments is not fully mapped. +.It Bq Er EFAULT +The +.Fa vec +argument points to an illegal address. +.El +.Sh SEE ALSO +.Xr madvise 2 , +.Xr mlock 2 , +.Xr mprotect 2 , +.Xr msync 2 , +.Xr munmap 2 , +.Xr getpagesize 3 , +.Xr getpagesizes 3 +.Sh HISTORY +The +.Fn mincore +system call first appeared in +.Bx 4.4 . diff --git a/lib/libsys/minherit.2 b/lib/libsys/minherit.2 new file mode 100644 index 000000000000..7240b8473656 --- /dev/null +++ b/lib/libsys/minherit.2 @@ -0,0 +1,148 @@ +.\" +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd March 15, 2017 +.Dt MINHERIT 2 +.Os +.Sh NAME +.Nm minherit +.Nd control the inheritance of pages +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/mman.h +.Ft int +.Fn minherit "void *addr" "size_t len" "int inherit" +.Sh DESCRIPTION +The +.Fn minherit +system call +changes the specified pages to have the inheritance characteristic +.Fa inherit . +Not all implementations will guarantee that the inheritance characteristic +can be set on a page basis; +the granularity of changes may be as large as an entire region. +.Fx +is capable of adjusting inheritance characteristics on a page basis. +Inheritance only effects children created by +.Fn fork . +It has no effect on +.Fn exec . +exec'd processes replace their address space entirely. +This system call also +has no effect on the parent's address space (other than to potentially +share the address space with its children). +.Pp +Inheritance is a rather esoteric feature largely superseded by the +.Dv MAP_SHARED +feature of +.Fn mmap . +However, it is possible to use +.Fn minherit +to share a block of memory between parent and child that has been mapped +.Dv MAP_PRIVATE . +That is, modifications made by parent or child are shared but +the original underlying file is left untouched. +.Bl -tag -width ".Dv INHERIT_SHARE" +.It Dv INHERIT_SHARE +This option causes the address space in question to be shared between +parent and child. +It has no effect on how the original underlying backing +store was mapped. +.It Dv INHERIT_NONE +This option prevents the address space in question from being inherited +at all. +The address space will be unmapped in the child. +.It Dv INHERIT_COPY +This option causes the child to inherit the address space as copy-on-write. +This option also has an unfortunate side effect of causing the parent +address space to become copy-on-write when the parent forks. +If the original mapping was +.Dv MAP_SHARED , +it will no longer be shared in the parent +after the parent forks and there is no way to get the previous +shared-backing-store mapping without unmapping and remapping the address +space in the parent. +.It Dv INHERIT_ZERO +This option causes the address space in question to be mapped as new +anonymous pages, +which would be initialized to all zero bytes, +in the child process. +.El +.Sh RETURN VALUES +.Rv -std minherit +.Sh ERRORS +The +.Fn minherit +system call will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The virtual address range specified by the +.Fa addr +and +.Fa len +arguments is not valid. +.It Bq Er EACCES +The flags specified by the +.Fa inherit +argument were not valid for the pages specified +by the +.Fa addr +and +.Fa len +arguments. +.El +.Sh SEE ALSO +.Xr fork 2 , +.Xr madvise 2 , +.Xr mincore 2 , +.Xr mprotect 2 , +.Xr msync 2 , +.Xr munmap 2 , +.Xr rfork 2 +.Sh HISTORY +The +.Fn minherit +system call first appeared in +.Ox +and then in +.Fx 2.2 . +.Pp +The +.Dv INHERIT_ZERO +support first appeared in +.Ox 5.6 +and then in +.Fx 12.0 . +.Sh BUGS +Once you set inheritance to +.Dv MAP_PRIVATE +or +.Dv MAP_SHARED , +there is no way to recover the original copy-on-write semantics +short of unmapping and remapping the area. diff --git a/lib/libsys/mkdir.2 b/lib/libsys/mkdir.2 new file mode 100644 index 000000000000..100f44d1dcf9 --- /dev/null +++ b/lib/libsys/mkdir.2 @@ -0,0 +1,179 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd March 30, 2020 +.Dt MKDIR 2 +.Os +.Sh NAME +.Nm mkdir , +.Nm mkdirat +.Nd make a directory file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/stat.h +.Ft int +.Fn mkdir "const char *path" "mode_t mode" +.Ft int +.Fn mkdirat "int fd" "const char *path" "mode_t mode" +.Sh DESCRIPTION +The directory +.Fa path +is created with the access permissions specified by +.Fa mode +and restricted by the +.Xr umask 2 +of the calling process. +.Pp +The directory's owner ID is set to the process's effective user ID. +The directory's group ID is set to that of the parent directory in +which it is created. +.Pp +The +.Fn mkdirat +system call is equivalent to +.Fn mkdir +except in the case where +.Fa path +specifies a relative path. +In this case the newly created directory is created relative to the +directory associated with the file descriptor +.Fa fd +instead of the current working directory. +If +.Fn mkdirat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is +identical to a call to +.Fn mkdir . +.Sh RETURN VALUES +.Rv -std mkdir +.Sh ERRORS +The +.Fn mkdir +system call +will fail and no directory will be created if: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +A component of the path prefix does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix, +or write permission is denied +on the parent directory of the directory to be created. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EPERM +The parent directory of the directory to be created has its immutable flag set, +see the +.Xr chflags 2 +manual page for more information. +.It Bq Er EROFS +The named directory would reside on a read-only file system. +.It Bq Er EMLINK +The new directory cannot be created because the parent directory contains +too many subdirectories. +.It Bq Er EEXIST +The named file exists. +.It Bq Er ENOSPC +The new directory cannot be created because there is no space left +on the file system that will contain the directory. +.It Bq Er ENOSPC +There are no free inodes on the file system on which the +directory is being created. +.It Bq Er EDQUOT +The new directory cannot be created because the user's +quota of disk blocks on the file system that will +contain the directory has been exhausted. +.It Bq Er EDQUOT +The user's quota of inodes on the file system on +which the directory is being created has been exhausted. +.It Bq Er EIO +An I/O error occurred while making the directory entry or allocating the inode. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.El +.Pp +In addition to the errors returned by the +.Fn mkdir , +the +.Fn mkdirat +may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El +.Sh SEE ALSO +.Xr chflags 2 , +.Xr chmod 2 , +.Xr stat 2 , +.Xr umask 2 +.Sh STANDARDS +The +.Fn mkdir +system call is expected to conform to +.St -p1003.1-90 . +The +.Fn mkdirat +system call follows The Open Group Extended API Set 2 specification. +.Sh HISTORY +The +.Fn mkdirat +system call appeared in +.Fx 8.0 . +The +.Fn mkdir +system call appeared in +.Bx 4.2 . diff --git a/lib/libsys/mkfifo.2 b/lib/libsys/mkfifo.2 new file mode 100644 index 000000000000..3af12fb14b64 --- /dev/null +++ b/lib/libsys/mkfifo.2 @@ -0,0 +1,180 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd March 30, 2020 +.Dt MKFIFO 2 +.Os +.Sh NAME +.Nm mkfifo , +.Nm mkfifoat +.Nd make a fifo file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/stat.h +.Ft int +.Fn mkfifo "const char *path" "mode_t mode" +.Ft int +.Fn mkfifoat "int fd" "const char *path" "mode_t mode" +.Sh DESCRIPTION +The +.Fn mkfifo +system call +creates a new fifo file with name +.Fa path . +The access permissions are +specified by +.Fa mode +and restricted by the +.Xr umask 2 +of the calling process. +.Pp +The fifo's owner ID is set to the process's effective user ID. +The fifo's group ID is set to that of the parent directory in +which it is created. +.Pp +The +.Fn mkfifoat +system call is equivalent to +.Fn mkfifo +except in the case where +.Fa path +specifies a relative path. +In this case the newly created FIFO is created relative to the +directory associated with the file descriptor +.Fa fd +instead of the current working directory. +If +.Fn mkfifoat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is +identical to a call to +.Fn mkfifo . +.Sh RETURN VALUES +.Rv -std mkfifo +.Sh ERRORS +The +.Fn mkfifo +system call +will fail and no fifo will be created if: +.Bl -tag -width Er +.It Bq Er ENOTSUP +The kernel has not been configured to support fifo's. +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +A component of the path prefix does not exist. +.It Bq Er EACCES +A component of the path prefix denies search permission, or write permission +is denied on the parent directory of the fifo to be created. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EROFS +The named file would reside on a read-only file system. +.It Bq Er EEXIST +The named file exists. +.It Bq Er EPERM +The parent directory of the named file has its immutable flag set, see the +.Xr chflags 2 +manual page for more information. +.It Bq Er ENOSPC +The directory in which the entry for the new fifo is being placed +cannot be extended because there is no space left on the file +system containing the directory. +.It Bq Er ENOSPC +There are no free inodes on the file system on which the +fifo is being created. +.It Bq Er EDQUOT +The directory in which the entry for the new fifo +is being placed cannot be extended because the +user's quota of disk blocks on the file system +containing the directory has been exhausted. +.It Bq Er EDQUOT +The user's quota of inodes on the file system on +which the fifo is being created has been exhausted. +.It Bq Er EIO +An +.Tn I/O +error occurred while making the directory entry or allocating the inode. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.El +.Pp +In addition to the errors returned by the +.Fn mkfifo , +the +.Fn mkfifoat +may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El +.Sh SEE ALSO +.Xr chflags 2 , +.Xr chmod 2 , +.Xr mknod 2 , +.Xr stat 2 , +.Xr umask 2 +.Sh STANDARDS +The +.Fn mkfifo +system call is expected to conform to +.St -p1003.1-90 . +The +.Fn mkfifoat +system call follows The Open Group Extended API Set 2 specification. +.Sh HISTORY +The +.Fn mkfifoat +system call appeared in +.Fx 8.0 . diff --git a/lib/libsys/mknod.2 b/lib/libsys/mknod.2 new file mode 100644 index 000000000000..f4327262b46b --- /dev/null +++ b/lib/libsys/mknod.2 @@ -0,0 +1,181 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd March 30, 2020 +.Dt MKNOD 2 +.Os +.Sh NAME +.Nm mknod , +.Nm mknodat +.Nd make a special file node +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/stat.h +.Ft int +.Fn mknod "const char *path" "mode_t mode" "dev_t dev" +.Ft int +.Fn mknodat "int fd" "const char *path" "mode_t mode" "dev_t dev" +.Sh DESCRIPTION +The file system node +.Fa path +is created with the file type and access permissions specified in +.Fa mode . +The access permissions are modified by the process's umask value. +.Pp +If +.Fa mode +indicates a block or character special file, +.Fa dev +is a configuration dependent specification denoting a particular device +on the system. +Otherwise, +.Fa dev +is ignored. +.Pp +The +.Fn mknod +system call +requires super-user privileges. +.Pp +The +.Fn mknodat +system call is equivalent to +.Fn mknod +except in the case where +.Fa path +specifies a relative path. +In this case the newly created device node is created relative to the +directory associated with the file descriptor +.Fa fd +instead of the current working directory. +If +.Fn mknodat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is +identical to a call to +.Fn mknod . +.Sh RETURN VALUES +.Rv -std mknod +.Sh ERRORS +The +.Fn mknod +system call +will fail and the file will be not created if: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +A component of the path prefix does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EPERM +The process's effective user ID is not super-user. +.It Bq Er EIO +An I/O error occurred while making the directory entry or allocating the inode. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.It Bq Er ENOSPC +The directory in which the entry for the new node is being placed +cannot be extended because there is no space left on the file +system containing the directory. +.It Bq Er ENOSPC +There are no free inodes on the file system on which the +node is being created. +.It Bq Er EDQUOT +The directory in which the entry for the new node +is being placed cannot be extended because the +user's quota of disk blocks on the file system +containing the directory has been exhausted. +.It Bq Er EDQUOT +The user's quota of inodes on the file system on +which the node is being created has been exhausted. +.It Bq Er EROFS +The named file resides on a read-only file system. +.It Bq Er EEXIST +The named file exists. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.It Bq Er EINVAL +Creating anything else than a block or character special +file (or a +.Em whiteout ) +is not supported. +.El +.Pp +In addition to the errors returned by the +.Fn mknod , +the +.Fn mknodat +may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El +.Sh SEE ALSO +.Xr chmod 2 , +.Xr mkfifo 2 , +.Xr stat 2 , +.Xr umask 2 +.Sh STANDARDS +The +.Fn mknodat +system call follows The Open Group Extended API Set 2 specification. +.Sh HISTORY +The +.Fn mknod +function appeared in +.At v4 . +The +.Fn mknodat +system call appeared in +.Fx 8.0 . diff --git a/lib/libsys/mlock.2 b/lib/libsys/mlock.2 new file mode 100644 index 000000000000..25346355a68a --- /dev/null +++ b/lib/libsys/mlock.2 @@ -0,0 +1,176 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd May 13, 2019 +.Dt MLOCK 2 +.Os +.Sh NAME +.Nm mlock , +.Nm munlock +.Nd lock (unlock) physical pages in memory +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/mman.h +.Ft int +.Fn mlock "const void *addr" "size_t len" +.Ft int +.Fn munlock "const void *addr" "size_t len" +.Sh DESCRIPTION +The +.Fn mlock +system call +locks into memory the physical pages associated with the virtual address +range starting at +.Fa addr +for +.Fa len +bytes. +The +.Fn munlock +system call unlocks pages previously locked by one or more +.Fn mlock +calls. +For both, the +.Fa addr +argument should be aligned to a multiple of the page size. +If the +.Fa len +argument is not a multiple of the page size, it will be rounded up +to be so. +The entire range must be allocated. +.Pp +After an +.Fn mlock +system call, the indicated pages will cause neither a non-resident page +nor address-translation fault until they are unlocked. +They may still cause protection-violation faults or TLB-miss faults on +architectures with software-managed TLBs. +The physical pages remain in memory until all locked mappings for the pages +are removed. +Multiple processes may have the same physical pages locked via their own +virtual address mappings. +A single process may likewise have pages multiply-locked via different virtual +mappings of the same physical pages. +Unlocking is performed explicitly by +.Fn munlock +or implicitly by a call to +.Fn munmap +which deallocates the unmapped address range. +Locked mappings are not inherited by the child process after a +.Xr fork 2 . +.Pp +Since physical memory is a potentially scarce resource, processes are +limited in how much they can lock down. +The amount of memory that a single process can +.Fn mlock +is limited by both the per-process +.Dv RLIMIT_MEMLOCK +resource limit and the +system-wide +.Dq wired pages +limit +.Va vm.max_user_wired . +.Va vm.max_user_wired +applies to the system as a whole, so the amount available to a single +process at any given time is the difference between +.Va vm.max_user_wired +and +.Va vm.stats.vm.v_user_wire_count . +.Pp +If +.Va security.bsd.unprivileged_mlock +is set to 0 these calls are only available to the super-user. +.Sh RETURN VALUES +.Rv -std +.Pp +If the call succeeds, all pages in the range become locked (unlocked); +otherwise the locked status of all pages in the range remains unchanged. +.Sh ERRORS +The +.Fn mlock +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +.Va security.bsd.unprivileged_mlock +is set to 0 and the caller is not the super-user. +.It Bq Er EINVAL +The address range given wraps around zero. +.It Bq Er ENOMEM +Some portion of the indicated address range is not allocated. +There was an error faulting/mapping a page. +Locking the indicated range would exceed the per-process or system-wide limits +for locked memory. +.El +The +.Fn munlock +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +.Va security.bsd.unprivileged_mlock +is set to 0 and the caller is not the super-user. +.It Bq Er EINVAL +The address range given wraps around zero. +.It Bq Er ENOMEM +Some or all of the address range specified by the addr and len +arguments does not correspond to valid mapped pages in the address space +of the process. +.It Bq Er ENOMEM +Locking the pages mapped by the specified range would exceed a limit on +the amount of memory that the process may lock. +.El +.Sh "SEE ALSO" +.Xr fork 2 , +.Xr mincore 2 , +.Xr minherit 2 , +.Xr mlockall 2 , +.Xr mmap 2 , +.Xr munlockall 2 , +.Xr munmap 2 , +.Xr setrlimit 2 , +.Xr getpagesize 3 +.Sh HISTORY +The +.Fn mlock +and +.Fn munlock +system calls first appeared in +.Bx 4.4 . +.Sh BUGS +Allocating too much wired memory can lead to a memory-allocation deadlock +which requires a reboot to recover from. +.Pp +The per-process and system-wide resource limits of locked memory apply +to the amount of virtual memory locked, not the amount of locked physical +pages. +Hence two distinct locked mappings of the same physical page counts as +2 pages aginst the system limit, and also against the per-process limit +if both mappings belong to the same physical map. +.Pp +The per-process resource limit is not currently supported. diff --git a/lib/libsys/mlockall.2 b/lib/libsys/mlockall.2 new file mode 100644 index 000000000000..58d3a9b0d78a --- /dev/null +++ b/lib/libsys/mlockall.2 @@ -0,0 +1,144 @@ +.\" $NetBSD: mlockall.2,v 1.11 2003/04/16 13:34:54 wiz Exp $ +.\" +.\" Copyright (c) 1999 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe of the Numerical Aerospace Simulation Facility, +.\" NASA Ames Research Center. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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. +.\" +.Dd May 13, 2019 +.Dt MLOCKALL 2 +.Os +.Sh NAME +.Nm mlockall , +.Nm munlockall +.Nd lock (unlock) the address space of a process +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/mman.h +.Ft int +.Fn mlockall "int flags" +.Ft int +.Fn munlockall "void" +.Sh DESCRIPTION +The +.Fn mlockall +system call locks into memory the physical pages associated with the +address space of a process until the address space is unlocked, the +process exits, or execs another program image. +.Pp +The following flags affect the behavior of +.Fn mlockall : +.Bl -tag -width ".Dv MCL_CURRENT" +.It Dv MCL_CURRENT +Lock all pages currently mapped into the process's address space. +.It Dv MCL_FUTURE +Lock all pages mapped into the process's address space in the future, +at the time the mapping is established. +Note that this may cause future mappings to fail if those mappings +cause resource limits to be exceeded. +.El +.Pp +Since physical memory is a potentially scarce resource, processes are +limited in how much they can lock down. +A single process can lock the minimum of a system-wide +.Dq wired pages +limit +.Va vm.max_user_wired +and the per-process +.Dv RLIMIT_MEMLOCK +resource limit. +.Pp +If +.Va security.bsd.unprivileged_mlock +is set to 0 these calls are only available to the super-user. +If +.Va vm.old_mlock +is set to 1 the per-process +.Dv RLIMIT_MEMLOCK +resource limit will not be applied for +.Fn mlockall +calls. +.Pp +The +.Fn munlockall +call unlocks any locked memory regions in the process address space. +Any regions mapped after an +.Fn munlockall +call will not be locked. +.Sh RETURN VALUES +A return value of 0 indicates that the call +succeeded and all pages in the range have either been locked or unlocked. +A return value of \-1 indicates an error occurred and the locked +status of all pages in the range remains unchanged. +In this case, the global location +.Va errno +is set to indicate the error. +.Sh ERRORS +.Fn mlockall +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa flags +argument is zero, or includes unimplemented flags. +.It Bq Er ENOMEM +Locking the indicated range would exceed either the system or per-process +limit for locked memory. +.It Bq Er EAGAIN +Some or all of the memory mapped into the process's address space +could not be locked when the call was made. +.It Bq Er EPERM +The calling process does not have the appropriate privilege to perform +the requested operation. +.El +.Sh SEE ALSO +.Xr mincore 2 , +.Xr mlock 2 , +.Xr mmap 2 , +.Xr munmap 2 , +.Xr setrlimit 2 +.Sh STANDARDS +The +.Fn mlockall +and +.Fn munlockall +functions are believed to conform to +.St -p1003.1-2001 . +.Sh HISTORY +The +.Fn mlockall +and +.Fn munlockall +functions first appeared in +.Fx 5.1 . +.Sh BUGS +The per-process and system-wide resource limits of locked memory apply +to the amount of virtual memory locked, not the amount of locked physical +pages. +Hence two distinct locked mappings of the same physical page counts as +2 pages aginst the system limit, and also against the per-process limit +if both mappings belong to the same physical map. diff --git a/lib/libsys/mmap.2 b/lib/libsys/mmap.2 new file mode 100644 index 000000000000..bc8f1a624a2e --- /dev/null +++ b/lib/libsys/mmap.2 @@ -0,0 +1,564 @@ +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd August 14, 2023 +.Dt MMAP 2 +.Os +.Sh NAME +.Nm mmap +.Nd allocate memory, or map files or devices into memory +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/mman.h +.Ft void * +.Fn mmap "void *addr" "size_t len" "int prot" "int flags" "int fd" "off_t offset" +.Sh DESCRIPTION +The +.Fn mmap +system call causes the pages starting at +.Fa addr +and continuing for at most +.Fa len +bytes to be mapped from the object described by +.Fa fd , +starting at byte offset +.Fa offset . +If +.Fa len +is not a multiple of the page size, the mapped region may extend past the +specified range. +Any such extension beyond the end of the mapped object will be zero-filled. +.Pp +If +.Fa fd +references a regular file or a shared memory object, the range of +bytes starting at +.Fa offset +and continuing for +.Fa len +bytes must be legitimate for the possible (not necessarily +current) offsets in the object. +In particular, the +.Fa offset +value cannot be negative. +If the object is truncated and the process later accesses a page that +is wholly within the truncated region, the access is aborted and a +.Dv SIGBUS +signal is delivered to the process. +.Pp +If +.Fa fd +references a device file, the interpretation of the +.Fa offset +value is device specific and defined by the device driver. +The virtual memory subsystem does not impose any restrictions on the +.Fa offset +value in this case, passing it unchanged to the driver. +.Pp +If +.Fa addr +is non-zero, it is used as a hint to the system. +(As a convenience to the system, the actual address of the region may differ +from the address supplied.) +If +.Fa addr +is zero, an address will be selected by the system. +The actual starting address of the region is returned. +A successful +.Fa mmap +deletes any previous mapping in the allocated address range. +.Pp +The protections (region accessibility) are specified in the +.Fa prot +argument by +.Em or Ns 'ing +the following values: +.Pp +.Bl -tag -width PROT_WRITE -compact +.It Dv PROT_NONE +Pages may not be accessed. +.It Dv PROT_READ +Pages may be read. +.It Dv PROT_WRITE +Pages may be written. +.It Dv PROT_EXEC +Pages may be executed. +.El +.Pp +In addition to these protection flags, +.Fx +provides the ability to set the maximum protection of a region allocated by +.Nm +and later altered by +.Xr mprotect 2 . +This is accomplished by +.Em or Ns 'ing +one or more +.Dv PROT_ +values wrapped in the +.Dv PROT_MAX() +macro into the +.Fa prot +argument. +.Pp +The +.Fa flags +argument specifies the type of the mapped object, mapping options and +whether modifications made to the mapped copy of the page are private +to the process or are to be shared with other references. +Sharing, mapping type and options are specified in the +.Fa flags +argument by +.Em or Ns 'ing +the following values: +.Bl -tag -width MAP_PREFAULT_READ +.It Dv MAP_32BIT +Request a region in the first 2GB of the current process's address space. +If a suitable region cannot be found, +.Fn mmap +will fail. +.It Dv MAP_ALIGNED Ns Pq Fa n +Align the region on a requested boundary. +If a suitable region cannot be found, +.Fn mmap +will fail. +The +.Fa n +argument specifies the binary logarithm of the desired alignment. +.It Dv MAP_ALIGNED_SUPER +Align the region to maximize the potential use of large +.Pq Dq super +pages. +If a suitable region cannot be found, +.Fn mmap +will fail. +The system will choose a suitable page size based on the size of +mapping. +The page size used as well as the alignment of the region may both be +affected by properties of the file being mapped. +In particular, +the physical address of existing pages of a file may require a specific +alignment. +The region is not guaranteed to be aligned on any specific boundary. +.It Dv MAP_ANON +Map anonymous memory not associated with any specific file. +The file descriptor used for creating +.Dv MAP_ANON +must be \-1. +The +.Fa offset +argument must be 0. +.\".It Dv MAP_FILE +.\"Mapped from a regular file or character-special device memory. +.It Dv MAP_ANONYMOUS +This flag is identical to +.Dv MAP_ANON +and is provided for compatibility. +.It Dv MAP_EXCL +This flag can only be used in combination with +.Dv MAP_FIXED . +Please see the definition of +.Dv MAP_FIXED +for the description of its effect. +.It Dv MAP_FIXED +Do not permit the system to select a different address than the one +specified. +If the specified address cannot be used, +.Fn mmap +will fail. +If +.Dv MAP_FIXED +is specified, +.Fa addr +must be a multiple of the page size. +If +.Dv MAP_EXCL +is not specified, a successful +.Dv MAP_FIXED +request replaces any previous mappings for the process' +pages in the range from +.Fa addr +to +.Fa addr ++ +.Fa len . +In contrast, if +.Dv MAP_EXCL +is specified, the request will fail if a mapping +already exists within the range. +.It Dv MAP_GUARD +Instead of a mapping, create a guard of the specified size. +Guards allow a process to create reservations in its address space, +which can later be replaced by actual mappings. +.Pp +.Fa mmap +will not create mappings in the address range of a guard unless +the request specifies +.Dv MAP_FIXED . +Guards can be destroyed with +.Xr munmap 2 . +Any memory access by a thread to the guarded range results +in the delivery of a +.Dv SIGSEGV +signal to that thread. +.It Dv MAP_NOCORE +Region is not included in a core file. +.It Dv MAP_NOSYNC +Causes data dirtied via this VM map to be flushed to physical media +only when necessary (usually by the pager) rather than gratuitously. +Typically this prevents the update daemons from flushing pages dirtied +through such maps and thus allows efficient sharing of memory across +unassociated processes using a file-backed shared memory map. +Without +this option any VM pages you dirty may be flushed to disk every so often +(every 30-60 seconds usually) which can create performance problems if you +do not need that to occur (such as when you are using shared file-backed +mmap regions for IPC purposes). +Dirty data will be flushed automatically when all mappings of an object are +removed and all descriptors referencing the object are closed. +Note that VM/file system coherency is +maintained whether you use +.Dv MAP_NOSYNC +or not. +This option is not portable +across +.Ux +platforms (yet), though some may implement the same behavior +by default. +.Pp +.Em WARNING ! +Extending a file with +.Xr ftruncate 2 , +thus creating a big hole, and then filling the hole by modifying a shared +.Fn mmap +can lead to severe file fragmentation. +In order to avoid such fragmentation you should always pre-allocate the +file's backing store by +.Fn write Ns ing +zero's into the newly extended area prior to modifying the area via your +.Fn mmap . +The fragmentation problem is especially sensitive to +.Dv MAP_NOSYNC +pages, because pages may be flushed to disk in a totally random order. +.Pp +The same applies when using +.Dv MAP_NOSYNC +to implement a file-based shared memory store. +It is recommended that you create the backing store by +.Fn write Ns ing +zero's to the backing file rather than +.Fn ftruncate Ns ing +it. +You can test file fragmentation by observing the KB/t (kilobytes per +transfer) results from an +.Dq Li iostat 1 +while reading a large file sequentially, e.g.,\& using +.Dq Li dd if=filename of=/dev/null bs=32k . +.Pp +The +.Xr fsync 2 +system call will flush all dirty data and metadata associated with a file, +including dirty NOSYNC VM data, to physical media. +The +.Xr sync 8 +command and +.Xr sync 2 +system call generally do not flush dirty NOSYNC VM data. +The +.Xr msync 2 +system call is usually not needed since +.Bx +implements a coherent file system buffer cache. +However, it may be +used to associate dirty VM pages with file system buffers and thus cause +them to be flushed to physical media sooner rather than later. +.It Dv MAP_PREFAULT_READ +Immediately update the calling process's lowest-level virtual address +translation structures, such as its page table, so that every memory +resident page within the region is mapped for read access. +Ordinarily these structures are updated lazily. +The effect of this option is to eliminate any soft faults that would +otherwise occur on the initial read accesses to the region. +Although this option does not preclude +.Fa prot +from including +.Dv PROT_WRITE , +it does not eliminate soft faults on the initial write accesses to the +region. +.It Dv MAP_PRIVATE +Modifications are private. +.It Dv MAP_SHARED +Modifications are shared. +.It Dv MAP_STACK +Creates both a mapped region that grows downward on demand and an +adjoining guard that both reserves address space for the mapped region +to grow into and limits the mapped region's growth. +Together, the mapped region and the guard occupy +.Fa len +bytes of the address space. +The guard starts at the returned address, and the mapped region ends at +the returned address plus +.Fa len +bytes. +Upon access to the guard, the mapped region automatically grows in size, +and the guard shrinks by an equal amount. +Essentially, the boundary between the guard and the mapped region moves +downward so that the access falls within the enlarged mapped region. +However, the guard will never shrink to less than the number of pages +specified by the sysctl +.Dv security.bsd.stack_guard_page , +thereby ensuring that a gap for detecting stack overflow always exists +between the downward growing mapped region and the closest mapped region +beneath it. +.Pp +.Dv MAP_STACK +implies +.Dv MAP_ANON +and +.Fa offset +of 0. +The +.Fa fd +argument +must be -1 and +.Fa prot +must include at least +.Dv PROT_READ +and +.Dv PROT_WRITE . +The size of the guard, in pages, is specified by sysctl +.Dv security.bsd.stack_guard_page . +.El +.Pp +The +.Xr close 2 +system call does not unmap pages, see +.Xr munmap 2 +for further information. +.Sh NOTES +Although this implementation does not impose any alignment restrictions on +the +.Fa offset +argument, a portable program must only use page-aligned values. +.Pp +Large page mappings require that the pages backing an object be +aligned in matching blocks in both the virtual address space and RAM. +The system will automatically attempt to use large page mappings when +mapping an object that is already backed by large pages in RAM by +aligning the mapping request in the virtual address space to match the +alignment of the large physical pages. +The system may also use large page mappings when mapping portions of an +object that are not yet backed by pages in RAM. +The +.Dv MAP_ALIGNED_SUPER +flag is an optimization that will align the mapping request to the +size of a large page similar to +.Dv MAP_ALIGNED , +except that the system will override this alignment if an object already +uses large pages so that the mapping will be consistent with the existing +large pages. +This flag is mostly useful for maximizing the use of large pages on the +first mapping of objects that do not yet have pages present in RAM. +.Sh RETURN VALUES +Upon successful completion, +.Fn mmap +returns a pointer to the mapped region. +Otherwise, a value of +.Dv MAP_FAILED +is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn mmap +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EACCES +The flag +.Dv PROT_READ +was specified as part of the +.Fa prot +argument and +.Fa fd +was not open for reading. +The flags +.Dv MAP_SHARED +and +.Dv PROT_WRITE +were specified as part of the +.Fa flags +and +.Fa prot +argument and +.Fa fd +was not open for writing. +.It Bq Er EBADF +The +.Fa fd +argument +is not a valid open file descriptor. +.It Bq Er EINVAL +An invalid (negative) value was passed in the +.Fa offset +argument, when +.Fa fd +referenced a regular file or shared memory. +.It Bq Er EINVAL +An invalid value was passed in the +.Fa prot +argument. +.It Bq Er EINVAL +An undefined option was set in the +.Fa flags +argument. +.It Bq Er EINVAL +Both +.Dv MAP_PRIVATE +and +.Dv MAP_SHARED +were specified. +.It Bq Er EINVAL +None of +.Dv MAP_ANON , +.Dv MAP_GUARD , +.Dv MAP_PRIVATE , +.Dv MAP_SHARED , +or +.Dv MAP_STACK +was specified. +At least one of these flags must be included. +.It Bq Er EINVAL +.Dv MAP_STACK +was specified and +.Va len +is less than or equal to the guard size. +.It Bq Er EINVAL +.Dv MAP_FIXED +was specified and the +.Fa addr +argument was not page aligned, or part of the desired address space +resides out of the valid address space for a user process. +.It Bq Er EINVAL +Both +.Dv MAP_FIXED +and +.Dv MAP_32BIT +were specified and part of the desired address space resides outside +of the first 2GB of user address space. +.It Bq Er EINVAL +The +.Fa len +argument +was equal to zero. +.It Bq Er EINVAL +.Dv MAP_ALIGNED +was specified and the desired alignment was either larger than the +virtual address size of the machine or smaller than a page. +.It Bq Er EINVAL +.Dv MAP_ANON +was specified and the +.Fa fd +argument was not -1. +.It Bq Er EINVAL +.Dv MAP_ANON +was specified and the +.Fa offset +argument was not 0. +.It Bq Er EINVAL +Both +.Dv MAP_FIXED +and +.Dv MAP_EXCL +were specified, but the requested region is already used by a mapping. +.It Bq Er EINVAL +.Dv MAP_EXCL +was specified, but +.Dv MAP_FIXED +was not. +.It Bq Er EINVAL +.Dv MAP_GUARD +was specified, but the +.Fa offset +argument was not zero, the +.Fa fd +argument was not -1, or the +.Fa prot +argument was not +.Dv PROT_NONE . +.It Bq Er EINVAL +.Dv MAP_GUARD +was specified together with one of the flags +.Dv MAP_ANON , +.Dv MAP_PREFAULT , +.Dv MAP_PREFAULT_READ , +.Dv MAP_PRIVATE , +.Dv MAP_SHARED , +.Dv MAP_STACK . +.It Bq Er ENODEV +.Dv MAP_ANON +has not been specified and +.Fa fd +did not reference a regular or character special file. +.It Bq Er ENOMEM +.Dv MAP_FIXED +was specified and the +.Fa addr +argument was not available. +.Dv MAP_ANON +was specified and insufficient memory was available. +.It Bq Er ENOTSUP +The +.Fa prot +argument contains protections which are not a subset of the specified +maximum protections. +.El +.Sh SEE ALSO +.Xr madvise 2 , +.Xr mincore 2 , +.Xr minherit 2 , +.Xr mlock 2 , +.Xr mprotect 2 , +.Xr msync 2 , +.Xr munlock 2 , +.Xr munmap 2 , +.Xr getpagesize 3 , +.Xr getpagesizes 3 +.Sh HISTORY +The +.Nm +system call was first documented in +.Bx 4.2 +and implemented in +.Bx 4.4 . +.\" XXX: lots of missing history of FreeBSD additions. +.Pp +The +.Dv PROT_MAX +functionality was introduced in +.Fx 13 . diff --git a/lib/libsys/modfind.2 b/lib/libsys/modfind.2 new file mode 100644 index 000000000000..df6c8d6fd1ad --- /dev/null +++ b/lib/libsys/modfind.2 @@ -0,0 +1,84 @@ +.\" +.\" Copyright (c) 1999 Chris Costello +.\" All rights reserved. +.\" +.\" 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. +.\" +.Dd September 28, 2000 +.Dt MODFIND 2 +.Os +.Sh NAME +.Nm modfind +.Nd returns the modid of a kernel module +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/module.h +.Ft int +.Fn modfind "const char *modname" +.Sh DESCRIPTION +The +.Fn modfind +system call +returns the modid of the kernel module referenced by +.Fa modname . +.Sh RETURN VALUES +The +.Fn modfind +system call +returns the modid of the kernel module referenced by +.Fa modname . +Upon error, +.Fn modfind +returns -1 and sets +.Va errno +to indicate the error. +.Sh ERRORS +.Va errno +is set to the following if +.Fn modfind +fails: +.Bl -tag -width Er +.It Bq Er EFAULT +The data required for this operation could not be read from the kernel space. +.It Bq Er ENOENT +The file specified is not loaded in the kernel. +.El +.Sh SEE ALSO +.Xr kldfind 2 , +.Xr kldfirstmod 2 , +.Xr kldload 2 , +.Xr kldnext 2 , +.Xr kldstat 2 , +.Xr kldsym 2 , +.Xr kldunload 2 , +.Xr modfnext 2 , +.Xr modnext 2 , +.Xr modstat 2 , +.Xr kld 4 , +.Xr kldstat 8 +.Sh HISTORY +The +.Nm kld +interface first appeared in +.Fx 3.0 . diff --git a/lib/libsys/modnext.2 b/lib/libsys/modnext.2 new file mode 100644 index 000000000000..863d28688aaf --- /dev/null +++ b/lib/libsys/modnext.2 @@ -0,0 +1,95 @@ +.\" +.\" Copyright (c) 1999 Chris Costello +.\" All rights reserved. +.\" +.\" 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. +.\" +.Dd September 28, 2000 +.Dt MODNEXT 2 +.Os +.Sh NAME +.Nm modnext +.Nd return the modid of the next kernel module +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/module.h +.Ft int +.Fn modnext "int modid" +.Ft int +.Fn modfnext "int modid" +.Sh DESCRIPTION +The +.Fn modnext +system call +returns the modid of the next kernel module (that is, the one after +.Va modid ) +or 0 if +.Va modid +is the last module in the list. +.Pp +If the +.Va modid +value is 0, then +.Fn modnext +will return the modid of the first module. +The +.Fn modfnext +system call +must always be given a valid modid. +.Sh RETURN VALUES +The +.Fn modnext +system call +returns the modid of the next module (see +.Sx DESCRIPTION ) +or 0. +If an error +occurs, +.Va errno +is set to indicate the error. +.Sh ERRORS +The only error set by +.Fn modnext +is +.Er ENOENT , +which is set when +.Va modid +refers to a kernel module that does not exist (is not loaded). +.Sh SEE ALSO +.Xr kldfind 2 , +.Xr kldfirstmod 2 , +.Xr kldload 2 , +.Xr kldnext 2 , +.Xr kldstat 2 , +.Xr kldsym 2 , +.Xr kldunload 2 , +.Xr modfind 2 , +.Xr modstat 2 , +.Xr kld 4 , +.Xr kldstat 8 +.Sh HISTORY +The +.Nm kld +interface first appeared in +.Fx 3.0 . diff --git a/lib/libsys/modstat.2 b/lib/libsys/modstat.2 new file mode 100644 index 000000000000..cea7094cd586 --- /dev/null +++ b/lib/libsys/modstat.2 @@ -0,0 +1,125 @@ +.\" +.\" Copyright (c) 1999 Chris Costello +.\" All rights reserved. +.\" +.\" 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. +.\" +.Dd July 15, 2008 +.Dt MODSTAT 2 +.Os +.Sh NAME +.Nm modstat +.Nd get status of kernel module +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/module.h +.Ft int +.Fn modstat "int modid" "struct module_stat *stat" +.Sh DESCRIPTION +The +.Fn modstat +system call writes the info for the kernel module referred to by +.Fa modid +into +.Fa stat . +.Bd -literal +struct module_stat { + int version; /* set to sizeof(module_stat) */ + char name[MAXMODNAME]; + int refs; + int id; + modspecific_t data; +}; +typedef union modspecific { + int intval; + u_int uintval; + long longval; + u_long ulongval; +} modspecific_t; +.Ed +.Bl -tag -width XXXaddress +.It version +This field is set to the size of the structure mentioned above by the code +calling +.Fn modstat , +and not +.Fn modstat +itself. +.It name +The name of the module referred to by +.Fa modid . +.It refs +The number of modules referenced by +.Fa modid . +.It id +The id of the module specified in +.Fa modid . +.It data +Module specific data. +.El +.Sh RETURN VALUES +.Rv -std modstat +.Sh ERRORS +The information for the module referred to by +.Fa modid +is filled into the structure pointed to by +.Fa stat +unless: +.Bl -tag -width Er +.It Bq Er ENOENT +The module was not found (probably not loaded). +.It Bq Er EINVAL +The version specified in the +.Fa version +field of stat is not the proper version. +You would need to rebuild world, the +kernel, or your application, if this error occurs, given that you did properly +fill in the +.Fa version +field. +.It Bq Er EFAULT +There was a problem copying one, some, or all of the fields into +.Fa stat +in the +.Xr copyout 9 +function. +.El +.Sh SEE ALSO +.Xr kldfind 2 , +.Xr kldfirstmod 2 , +.Xr kldload 2 , +.Xr kldnext 2 , +.Xr kldstat 2 , +.Xr kldsym 2 , +.Xr kldunload 2 , +.Xr modfind 2 , +.Xr modfnext 2 , +.Xr modnext 2 , +.Xr kld 4 , +.Xr kldstat 8 +.Sh HISTORY +The +.Nm kld +interface first appeared in +.Fx 3.0 . diff --git a/lib/libsys/mount.2 b/lib/libsys/mount.2 new file mode 100644 index 000000000000..62e82c0b8184 --- /dev/null +++ b/lib/libsys/mount.2 @@ -0,0 +1,400 @@ +.\" Copyright (c) 1980, 1989, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd March 30, 2020 +.Dt MOUNT 2 +.Os +.Sh NAME +.Nm mount , +.Nm nmount , +.Nm unmount +.Nd mount or dismount a file system +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.Ft int +.Fn mount "const char *type" "const char *dir" "int flags" "void *data" +.Ft int +.Fn unmount "const char *dir" "int flags" +.In sys/uio.h +.Ft int +.Fn nmount "struct iovec *iov" "u_int niov" "int flags" +.Sh DESCRIPTION +The +.Fn mount +system call grafts +a file system object onto the system file tree +at the point +.Fa dir . +The argument +.Fa data +describes the file system object to be mounted. +The argument +.Fa type +tells the kernel how to interpret +.Fa data +(See +.Fa type +below). +The contents of the file system +become available through the new mount point +.Fa dir . +Any files in +.Fa dir +at the time +of a successful mount are swept under the carpet so to speak, and +are unavailable until the file system is unmounted. +.Pp +The +.Fn nmount +system call behaves similarly to +.Fn mount , +except that the mount options (file system type name, device to mount, +mount-point name, etc.) are passed as an array of name-value pairs +in the array +.Fa iov , +containing +.Fa niov +elements. +The following options are required by all file systems: +.Bl -column fstype -offset indent +.It +.Li fstype Ta file system type name (e.g., Dq Li procfs ) +.It +.Li fspath Ta mount point pathname (e.g., Dq Li /proc ) +.El +.Pp +Depending on the file system type, other options may be +recognized or required; +for example, most disk-based file systems require a +.Dq Li from +option containing the pathname of a special device +in addition to the options listed above. +.Pp +By default only the super-user may call the +.Fn mount +system call. +This restriction can be removed by setting the +.Va vfs.usermount +.Xr sysctl 8 +variable +to a non-zero value; see the BUGS section for more information. +.Pp +The following +.Fa flags +may be specified to +suppress default semantics which affect file system access. +.Bl -tag -width MNT_SYNCHRONOUS +.It Dv MNT_RDONLY +The file system should be treated as read-only; +even the super-user may not write on it. +Specifying MNT_UPDATE without this option will upgrade +a read-only file system to read/write. +.It Dv MNT_NOEXEC +Do not allow files to be executed from the file system. +.It Dv MNT_NOSUID +Do not honor setuid or setgid bits on files when executing them. +This flag is set automatically when the caller is not the super-user. +.It Dv MNT_NOATIME +Disable update of file access times. +.It Dv MNT_SNAPSHOT +Create a snapshot of the file system. +This is currently only supported on UFS2 file systems, see +.Xr mksnap_ffs 8 +for more information. +.It Dv MNT_SUIDDIR +Directories with the SUID bit set chown new files to their own owner. +This flag requires the SUIDDIR option to have been compiled into the kernel +to have any effect. +See the +.Xr mount 8 +and +.Xr chmod 2 +pages for more information. +.It Dv MNT_SYNCHRONOUS +All I/O to the file system should be done synchronously. +.It Dv MNT_ASYNC +All I/O to the file system should be done asynchronously. +.It Dv MNT_FORCE +Force a read-write mount even if the file system appears to be unclean. +Dangerous. +Together with +.Dv MNT_UPDATE +and +.Dv MNT_RDONLY , +specify that the file system is to be forcibly downgraded to a read-only +mount even if some files are open for writing. +.It Dv MNT_NOCLUSTERR +Disable read clustering. +.It Dv MNT_NOCLUSTERW +Disable write clustering. +.It Dv MNT_NOCOVER +Do not mount over the root of another mount point. +.It Dv MNT_EMPTYDIR +Require an empty directory for the mount point directory. +.El +.Pp +The flag +.Dv MNT_UPDATE +indicates that the mount command is being applied +to an already mounted file system. +This allows the mount flags to be changed without requiring +that the file system be unmounted and remounted. +Some file systems may not allow all flags to be changed. +For example, +many file systems will not allow a change from read-write to read-only. +.Pp +The flag +.Dv MNT_RELOAD +causes the vfs subsystem to update its data structures pertaining to +the specified already mounted file system. +.Pp +The +.Fa type +argument names the file system. +The types of file systems known to the system can be obtained with +.Xr lsvfs 1 . +.Pp +The +.Fa data +argument +is a pointer to a structure that contains the type +specific arguments to mount. +The format for these argument structures is described in the +manual page for each file system. +By convention file system manual pages are named +by prefixing ``mount_'' to the name of the file system as returned by +.Xr lsvfs 1 . +Thus the +.Tn NFS +file system is described by the +.Xr mount_nfs 8 +manual page. +It should be noted that a manual page for default +file systems, known as UFS and UFS2, does not exist. +.Pp +The +.Fn unmount +system call disassociates the file system from the specified +mount point +.Fa dir . +.Pp +The +.Fa flags +argument may include +.Dv MNT_FORCE +to specify that the file system should be forcibly unmounted +even if files are still active. +Active special devices continue to work, +but any further accesses to any other active files result in errors +even if the file system is later remounted. +.Pp +If the +.Dv MNT_BYFSID +flag is specified, +.Fa dir +should instead be a file system ID encoded as +.Dq Li FSID : Ns Ar val0 : Ns Ar val1 , +where +.Ar val0 +and +.Ar val1 +are the contents of the +.Vt fsid_t +.Va val[] +array in decimal. +The file system that has the specified file system ID will be unmounted. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn mount +and +.Fn nmount +system calls will fail when one of the following occurs: +.Bl -tag -width Er +.It Bq Er EPERM +The caller is neither the super-user nor the owner of +.Fa dir . +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or the entire length of a path name exceeded 1023 characters. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating a pathname. +.It Bq Er ENOENT +A component of +.Fa dir +does not exist. +.It Bq Er ENOTDIR +A component of +.Fa name +is not a directory, +or a path prefix of +.Fa special +is not a directory. +.It Bq Er EBUSY +Another process currently holds a reference to +.Fa dir . +.It Bq Er EBUSY +The +.Dv MNT_NOCOVER +option was given, and the requested mount point +is already the root of another mount point. +.It Bq Er EFAULT +The +.Fa dir +argument +points outside the process's allocated address space. +.It Bq Er EIO +An I/O error occurred while reading data from +.Fa special . +.It Bq Er EINTEGRITY +The backing store for +.Fa special +detected corrupted data while reading. +.El +.Pp +The following errors can occur for a +.Em ufs +file system mount: +.Bl -tag -width Er +.It Bq Er ENODEV +A component of ufs_args +.Fa fspec +does not exist. +.It Bq Er ENOTBLK +The +.Fa fspec +argument +is not a block device. +.It Bq Er ENOTEMPTY +The +.Dv MNT_EMPTYDIR +option was specified, and the requested mount point +is not an empty directory. +.It Bq Er ENXIO +The major device number of +.Fa fspec +is out of range (this indicates no device driver exists +for the associated hardware). +.It Bq Er EBUSY +.Fa fspec +is already mounted. +.It Bq Er EMFILE +No space remains in the mount table. +.It Bq Er EINVAL +The super block for the file system had a bad magic +number or an out of range block size. +.It Bq Er EINTEGRITY +The super block for the file system had a bad check hash. +The check hash can usually be corrected by running +.Xr fsck 8 . +.It Bq Er ENOMEM +Not enough memory was available to read the cylinder +group information for the file system. +.It Bq Er EIO +An I/O error occurred while reading the super block or +cylinder group information. +.It Bq Er EFAULT +The +.Fa fspec +argument +points outside the process's allocated address space. +.El +.Pp +The following errors can occur for a +.Em nfs +file system mount: +.Bl -tag -width Er +.It Bq Er ETIMEDOUT +.Em Nfs +timed out trying to contact the server. +.It Bq Er EFAULT +Some part of the information described by nfs_args +points outside the process's allocated address space. +.El +.Pp +The +.Fn unmount +system call may fail with one of the following errors: +.Bl -tag -width Er +.It Bq Er EPERM +The caller is neither the super-user nor the user who issued the corresponding +.Fn mount +call. +.It Bq Er ENAMETOOLONG +The length of the path name exceeded 1023 characters. +.It Bq Er EINVAL +The requested directory is not in the mount table. +.It Bq Er ENOENT +The file system ID specified using +.Dv MNT_BYFSID +was not found in the mount table. +.It Bq Er EINVAL +The file system ID specified using +.Dv MNT_BYFSID +could not be decoded. +.It Bq Er EINVAL +The specified file system is the root file system. +.It Bq Er EBUSY +A process is holding a reference to a file located +on the file system. +.It Bq Er EIO +An I/O error occurred while writing cached file system information. +.It Bq Er EFAULT +The +.Fa dir +argument +points outside the process's allocated address space. +.El +.Sh SEE ALSO +.Xr lsvfs 1 , +.Xr mksnap_ffs 8 , +.Xr mount 8 , +.Xr umount 8 +.Sh HISTORY +The +.Fn mount +and +.Fn unmount +functions appeared in +.At v1 . +The +.Fn nmount +system call first appeared in +.Fx 5.0 . +.Sh BUGS +Some of the error codes need translation to more obvious messages. +.Pp +Allowing untrusted users to mount arbitrary media, e.g. by enabling +.Va vfs.usermount , +should not be considered safe. +Most file systems in +.Fx +were not built to safeguard against malicious devices. diff --git a/lib/libsys/mprotect.2 b/lib/libsys/mprotect.2 new file mode 100644 index 000000000000..42e47b8cdaca --- /dev/null +++ b/lib/libsys/mprotect.2 @@ -0,0 +1,128 @@ +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd September 7, 2021 +.Dt MPROTECT 2 +.Os +.Sh NAME +.Nm mprotect +.Nd control the protection of pages +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/mman.h +.Ft int +.Fn mprotect "void *addr" "size_t len" "int prot" +.Sh DESCRIPTION +The +.Fn mprotect +system call +changes the specified pages to have protection +.Fa prot . +.Pp +The +.Fa prot +argument shall be +.Dv PROT_NONE +(no permissions at all) +or the bitwise +.Em or +of one or more of the following values: +.Pp +.Bl -tag -width ".Dv PROT_WRITE" -compact +.It Dv PROT_READ +The pages can be read. +.It Dv PROT_WRITE +The pages can be written. +.It Dv PROT_EXEC +The pages can be executed. +.El +.Pp +In addition to these standard protection flags, +the +.Fx +implementation of +.Fn mprotect +provides the ability to set the maximum protection of a region +(which prevents +.Nm +from adding to the permissions later). +This is accomplished by bitwise +.Em or Ns 'ing +one or more +.Dv PROT_ +values wrapped in the +.Dv PROT_MAX() +macro into the +.Fa prot +argument. +.Sh RETURN VALUES +.Rv -std mprotect +.Sh ERRORS +The +.Fn mprotect +system call will fail if: +.Bl -tag -width Er +.It Bq Er EACCES +The calling process was not allowed to change +the protection to the value specified by +the +.Fa prot +argument. +.It Bq Er EINVAL +The virtual address range specified by the +.Fa addr +and +.Fa len +arguments is not valid. +.It Bq Er EINVAL +The +.Fa prot +argument contains unhandled bits. +.It Bq Er ENOTSUP +The +.Fa prot +argument contains permissions which are not a subset of the specified +maximum permissions. +.El +.Sh SEE ALSO +.Xr madvise 2 , +.Xr mincore 2 , +.Xr msync 2 , +.Xr munmap 2 +.Sh HISTORY +The +.Fn mprotect +system call was first documented in +.Bx 4.2 +and first appeared in +.Bx 4.4 . +.Pp +The +.Dv PROT_MAX +functionality was introduced in +.Fx 13 . diff --git a/lib/libsys/mq_close.2 b/lib/libsys/mq_close.2 new file mode 100644 index 000000000000..315e09d2cd16 --- /dev/null +++ b/lib/libsys/mq_close.2 @@ -0,0 +1,103 @@ +.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org> +.\" All rights reserved. +.\" +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.Dd November 29, 2005 +.Dt MQ_CLOSE 2 +.Os +.Sh NAME +.Nm mq_close +.Nd "close a message queue (REALTIME)" +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft int +.Fn mq_close "mqd_t mqdes" +.Sh DESCRIPTION +The +.Fn mq_close +system call removes the association between the message queue descriptor, +.Fa mqdes , +and its message queue. +The results of using this message queue descriptor +after successful return from this +.Fn mq_close , +and until the return of this message queue descriptor from a subsequent +.Fn mq_open , +are undefined. +.Pp +If the process has successfully attached a notification request to the +message queue via this +.Fa mqdes , +this attachment will be removed, and the message queue is available for +another process to attach for notification. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn mq_close +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa mqdes +argument is not a valid message queue descriptor. +.El +.Sh SEE ALSO +.Xr mq_open 2 , +.Xr mq_unlink 2 +.Sh STANDARDS +The +.Fn mq_close +system call conforms to +.St -p1003.1-2004 . +.Sh HISTORY +Support for +.Tn POSIX +message queues first appeared in +.Fx 7.0 . +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard is +the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html. diff --git a/lib/libsys/mq_getattr.2 b/lib/libsys/mq_getattr.2 new file mode 100644 index 000000000000..b764cfac0fa3 --- /dev/null +++ b/lib/libsys/mq_getattr.2 @@ -0,0 +1,125 @@ +.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org> +.\" All rights reserved. +.\" +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.Dd February 21, 2014 +.Dt MQ_GETATTR 2 +.Os +.Sh NAME +.Nm mq_getattr +.Nd "get message queue attributes (REALTIME)" +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft int +.Fn mq_getattr "mqd_t mqdes" "struct mq_attr *mqstat" +.Sh DESCRIPTION +The +.Fn mq_getattr +system call obtains status information and attributes of the message queue and +the open message queue description associated with the message queue +descriptor. +.Pp +The +.Fa mqdes +argument specifies a message queue descriptor. +.Pp +The results are returned in the +.Vt mq_attr +structure referenced by the +.Fa mqstat +argument. +.Pp +Upon return, the following members will have the values associated with the +open message queue description as set when the message queue was opened and +as modified by subsequent +.Fn mq_setattr +calls: +.Va mq_flags . +.Pp +The following attributes of the message queue will be returned as set at +message queue creation: +.Va mq_maxmsg , mq_msgsize . +.Pp +Upon return, the following members within the +.Vt mq_attr +structure referenced by the +.Fa mqstat +argument will be set to the current state +of the message queue: +.Bl -tag -width ".Va mq_curmsgs" +.It Va mq_curmsgs +The number of messages currently on the queue. +.El +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn mq_getattr +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa mqdes +argument is not a valid message queue descriptor. +.El +.Sh SEE ALSO +.Xr mq_open 2 , +.Xr mq_send 2 , +.Xr mq_setattr 2 , +.Xr mq_timedsend 2 +.Sh STANDARDS +The +.Fn mq_getattr +system call conforms to +.St -p1003.1-2004 . +.Sh HISTORY +Support for +.Tn POSIX +message queues first appeared in +.Fx 7.0 . +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard is +the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html. diff --git a/lib/libsys/mq_notify.2 b/lib/libsys/mq_notify.2 new file mode 100644 index 000000000000..f2bf7aa6ebf4 --- /dev/null +++ b/lib/libsys/mq_notify.2 @@ -0,0 +1,163 @@ +.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org> +.\" All rights reserved. +.\" +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.Dd July 15, 2016 +.Dt MQ_NOTIFY 2 +.Os +.Sh NAME +.Nm mq_notify +.Nd "notify process that a message is available (REALTIME)" +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft int +.Fn mq_notify "mqd_t mqdes" "const struct sigevent *notification" +.Sh DESCRIPTION +If the argument notification is not +.Dv NULL , +this system call will register the calling process to be notified of message +arrival at an empty message queue associated with the specified message +queue descriptor, +.Fa mqdes . +The notification specified by the +.Fa notification +argument will be sent to +the process when the message queue transitions from empty to non-empty. +At any time, only one process may be registered for notification by a +message queue. +If the calling process or any other process has already +registered for notification of message arrival at the specified message +queue, subsequent attempts to register for that message queue will fail. +.Pp +The +.Fa notification +argument points to a +.Vt sigevent +structure that defines how the calling process will be notified. +If +.Fa notification->sigev_notify +is +.Dv SIGEV_NONE , +then no signal will be posted, but the error status and the return status +for the operation will be set appropriately. +For +.Dv SIGEV_SIGNO +and +.Dv SIGEV_THREAD_ID +notifications, +the signal specified in +.Fa notification->sigev_signo +will be sent to the calling process +.Pq Dv SIGEV_SIGNO +or to the thread whose LWP ID is +.Fa notification->sigev_notify_thread_id +.Pq Dv SIGEV_THREAD_ID . +The information for the queued signal will include: +.Bl -column ".Va si_value" +.It Sy Member Ta Sy Value +.It Va si_code Ta Dv SI_MESGQ +.It Va si_value Ta +the value stored in +.Fa notification->sigev_value +.It Va si_mqd Ta Fa mqdes +.El +.Pp +If +.Fa notification +is +.Dv NULL +and the process is currently registered for notification by the specified +message queue, the existing registration will be removed. +.Pp +When the notification is sent to the registered process, its registration +is removed. +The message queue then is available for registration. +.Pp +If a process has registered for notification of message arrival at a +message queue and some thread is blocked in +.Fn mq_receive +waiting to receive a message when a message arrives at the queue, the +arriving message will satisfy the appropriate +.Fn mq_receive . +The resulting behavior is as if the message queue remains empty, and no +notification will be sent. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn mq_notify +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa mqdes +argument is not a valid message queue descriptor. +.It Bq Er EBUSY +Process is already registered for notification by the message queue. +.It Bq Er EINVAL +The asynchronous notification method in +.Fa notification->sigev_notify +is invalid or not supported. +.El +.Sh SEE ALSO +.Xr mq_open 2 , +.Xr mq_send 2 , +.Xr mq_timedsend 2 , +.Xr sigevent 3 , +.Xr siginfo 3 +.Sh STANDARDS +The +.Fn mq_notify +system call conforms to +.St -p1003.1-2004 . +.Sh HISTORY +Support for +.Tn POSIX +message queues first appeared in +.Fx 7.0 . +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard is +the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html. diff --git a/lib/libsys/mq_open.2 b/lib/libsys/mq_open.2 new file mode 100644 index 000000000000..4800ab18de59 --- /dev/null +++ b/lib/libsys/mq_open.2 @@ -0,0 +1,344 @@ +.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org> +.\" All rights reserved. +.\" +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.Dd May 15, 2024 +.Dt MQ_OPEN 2 +.Os +.Sh NAME +.Nm mq_open +.Nd "open a message queue (REALTIME)" +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft mqd_t +.Fn mq_open "const char *name" "int oflag" "..." +.Sh DESCRIPTION +The +.Fn mq_open +system call establishes the connection between a process and a message queue +with a message queue descriptor. +It creates an open message queue +description that refers to the message queue, and a message queue descriptor +that refers to that open message queue description. +The message queue +descriptor is used by other functions to refer to that message queue. +The +.Fa name +argument points to a string naming a message queue. +The +.Fa name +argument should conform to the construction rules for a pathname. +The +.Fa name +should begin with a slash character. +Processes calling +.Fn mq_open +with the same value of +.Fa name +refers to the same message queue object, as long as that name has not been +removed. +If the +.Fa name +argument is not the name of an existing message queue and creation is not +requested, +.Fn mq_open +will fail and return an error. +.Pp +The +.Fa oflag +argument requests the desired receive and/or send access to the message +queue. +The requested access permission to receive messages or send messages +would be granted if the calling process would be granted read or write access, +respectively, to an equivalently protected file. +.Pp +The value of +.Fa oflag +is the bitwise-inclusive OR of values from the following list. +Applications should specify exactly one of the first three values (access +modes) below in the value of +.Fa oflag : +.Bl -tag -width ".Dv O_NONBLOCK" +.It Dv O_RDONLY +Open the message queue for receiving messages. +The process can use the +returned message queue descriptor with +.Fn mq_receive , +but not +.Fn mq_send . +A message queue may be open multiple times in the same or different processes +for receiving messages. +.It Dv O_WRONLY +Open the queue for sending messages. +The process can use the returned +message queue descriptor with +.Fn mq_send +but not +.Fn mq_receive . +A message queue may be open multiple times in the same or different processes +for sending messages. +.It Dv O_RDWR +Open the queue for both receiving and sending messages. +The process can use +any of the functions allowed for +.Dv O_RDONLY +and +.Dv O_WRONLY . +A message queue may be open multiple times in the same or different processes +for sending messages. +.El +.Pp +Any combination of the remaining flags may be specified in the value of +.Fa oflag : +.Bl -tag -width ".Dv O_NONBLOCK" +.It Dv O_CREAT +Create a message queue. +It requires two additional arguments: +.Fa mode , +which is of type +.Vt mode_t , +and +.Fa attr , +which is a pointer to an +.Vt mq_attr +structure. +If the pathname +.Fa name +has already been used to create a message queue that still exists, then +this flag has no effect, except as noted under +.Dv O_EXCL . +Otherwise, a message queue will be created without any messages +in it. +The user ID of the message queue will be set to the effective user ID +of the process, and the group ID of the message queue will be set to the +effective group ID of the process. +The permission bits of the message queue +will be set to the value of the +.Fa mode +argument, except those set in the file mode creation mask of the process. +When bits in +.Fa mode +other than the file permission bits are specified, the effect is +unspecified. +If +.Fa attr +is +.Dv NULL , +the message queue is created with implementation-defined default message +queue attributes. +If attr is +.Pf non- Dv NULL +and the calling process has the +appropriate privilege on name, the message queue +.Va mq_maxmsg +and +.Va mq_msgsize +attributes will be set to the values of the corresponding members in the +.Vt mq_attr +structure referred to by +.Fa attr . +If +.Fa attr +is +.Pf non- Dv NULL , +but the calling process does not have the appropriate privilege +on name, the +.Fn mq_open +function will fail and return an error without creating the message queue. +.It Dv O_EXCL +If +.Dv O_EXCL +and +.Dv O_CREAT +are set, +.Fn mq_open +will fail if the message queue name exists. +.It Dv O_NONBLOCK +Determines whether an +.Fn mq_send +or +.Fn mq_receive +waits for resources or messages that are not currently available, or fails +with +.Va errno +set to +.Er EAGAIN ; +see +.Xr mq_send 2 +and +.Xr mq_receive 2 +for details. +.El +.Pp +The +.Fn mq_open +system call does not add or remove messages from the queue. +.Sh NOTES +.Fx +implements message queue based on file descriptor. +The descriptor +is inherited by child after +.Xr fork 2 . +The descriptor is closed in a new image after +.Xr exec 3 . +The +.Xr select 2 +and +.Xr kevent 2 +system calls are supported for message queue descriptor. +.Pp +Please see the +.Xr mqueuefs 4 +man page for instructions on loading the module or compiling the service into +the kernel. +.Pp +The number of queues available, the maximum number of messages per queue +and the maximum message size are tunable +.Xr sysctl 8 +parameters. +Their defaults are as follows. +.Bl -column kern.mqueue.maxmsgsize integerxxx +.It Sy "Name Type Default" +.It "kern.mqueue.maxmq integer 100" +.It "kern.mqueue.maxmsgsize integer 16384" +.It "kern.mqueue.maxmsg integer 100" +.El +.Sh RETURN VALUES +Upon successful completion, the function returns a message queue +descriptor; otherwise, the function returns +.Po Vt mqd_t Pc Ns \-1 +and sets the global variable +.Va errno +to indicate the error. +.Sh ERRORS +The +.Fn mq_open +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EACCES +The message queue exists and the permissions specified by +.Fa oflag +are denied, or the message queue does not exist and permission to create the +message queue is denied. +.It Bq Er EEXIST +.Dv O_CREAT +and +.Dv O_EXCL +are set and the named message queue already exists. +.It Bq Er EINTR +The +.Fn mq_open +function was interrupted by a signal. +.It Bq Er EINVAL +The +.Fn mq_open +function is not supported for the given name. +.It Bq Er EINVAL +.Dv O_CREAT +was specified in +.Fa oflag , +the value of +.Fa attr +is not +.Dv NULL , +and either +.Va mq_maxmsg +or +.Va mq_msgsize +was less than or equal to zero. +.It Bq Er EMFILE +Too many message queue descriptors or file descriptors are currently in use +by this process. +.It Bq Er ENAMETOOLONG +The length of the +.Fa name +argument exceeds +.Brq Dv PATH_MAX +or a pathname component +is longer than +.Brq Dv NAME_MAX . +.It Bq Er ENFILE +Too many message queues are currently open in the system. +.It Bq Er ENOENT +.Dv O_CREAT +is not set and the named message queue does not exist. +.It Bq Er ENOSPC +There is insufficient space for the creation of the new message queue. +.El +.Sh SEE ALSO +.Xr mq_close 2 , +.Xr mq_getattr 2 , +.Xr mq_receive 2 , +.Xr mq_send 2 , +.Xr mq_setattr 2 , +.Xr mq_unlink 2 , +.Xr mq_timedreceive 3 , +.Xr mq_timedsend 3 , +.Xr mqueuefs 4 +.Sh STANDARDS +The +.Fn mq_open +system call conforms to +.St -p1003.1-2004 . +.Sh HISTORY +Support for POSIX message queues first appeared in +.Fx 7.0 . +.Sh BUGS +This implementation places strict requirements on the value of +.Fa name : +it may begin with a slash +.Pq Ql / +and contain no other slash characters. +.Pp +The +.Fa mode +and +.Fa attr +arguments are variadic and may result in different calling conventions +than might otherwise be expected. +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard is +the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html. diff --git a/lib/libsys/mq_receive.2 b/lib/libsys/mq_receive.2 new file mode 100644 index 000000000000..d210704249d7 --- /dev/null +++ b/lib/libsys/mq_receive.2 @@ -0,0 +1,215 @@ +.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org> +.\" All rights reserved. +.\" +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.Dd November 29, 2005 +.Dt MQ_RECEIVE 2 +.Os +.Sh NAME +.Nm mq_receive , mq_timedreceive +.Nd "receive a message from message queue (REALTIME)" +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft ssize_t +.Fo mq_receive +.Fa "mqd_t mqdes" +.Fa "char *msg_ptr" +.Fa "size_t msg_len" +.Fa "unsigned *msg_prio" +.Fc +.Ft ssize_t +.Fo mq_timedreceive +.Fa "mqd_t mqdes" +.Fa "char *msg_ptr" +.Fa "size_t msg_len" +.Fa "unsigned *msg_prio" +.Fa "const struct timespec *abs_timeout" +.Fc +.Sh DESCRIPTION +The +.Fn mq_receive +system call receives oldest of the highest priority message(s) from the +message queue specified by +.Fa mqdes . +If the size of the buffer in bytes, specified by the +.Fa msg_len +argument, is less than the +.Va mq_msgsize +attribute of the message queue, the system call will fail and return an +error. +Otherwise, the selected message will be removed from the queue +and copied to the buffer pointed to by the +.Fa msg_ptr +argument. +.Pp +If the argument +.Fa msg_prio +is not +.Dv NULL , +the priority of the selected message will be stored in the +location referenced by +.Fa msg_prio . +If the specified message queue is empty and +.Dv O_NONBLOCK +is not set in the message queue description associated with +.Fa mqdes , +.Fn mq_receive +will block until a message is enqueued on the message queue or until +.Fn mq_receive +is interrupted by a signal. +If more than one thread is waiting to receive +a message when a message arrives at an empty queue and the Priority +Scheduling option is supported, then the thread of highest priority that +has been waiting the longest will be selected to receive the message. +Otherwise, it is unspecified which waiting thread receives the message. +If the specified message queue is empty and +.Dv O_NONBLOCK +is set in the message queue description associated with +.Fa mqdes , +no message +will be removed from the queue, and +.Fn mq_receive +will return an error. +.Pp +The +.Fn mq_timedreceive +system call will receive the oldest of the highest priority messages from the +message queue specified by +.Fa mqdes +as described for the +.Fn mq_receive +system call. +However, if +.Dv O_NONBLOCK +was not specified when the message queue was opened via the +.Fn mq_open +system call, and no message exists on the queue to satisfy the receive, the wait +for such a message will be terminated when the specified timeout expires. +If +.Dv O_NONBLOCK +is set, this system call is equivalent to +.Fn mq_receive . +.Pp +The timeout expires when the absolute time specified by +.Fa abs_timeout +passes, as measured by the clock on which timeouts are based (that is, when +the value of that clock equals or exceeds +.Fa abs_timeout ) , +or if the absolute time specified by +.Fa abs_timeout +has already been passed at the time of the call. +.Pp +The timeout is based on the +.Dv CLOCK_REALTIME +clock. +.Sh RETURN VALUES +Upon successful completion, the +.Fn mq_receive +and +.Fn mq_timedreceive +system calls return the length of the selected message in bytes and the +message is removed from the queue. +Otherwise, no message is removed +from the queue, the system call returns a value of \-1, +and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn mq_receive +and +.Fn mq_timedreceive +system calls +will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +.Dv O_NONBLOCK +flag is set in the message queue description associated with +.Fa mqdes , +and the specified message queue is empty. +.It Bq Er EBADF +The +.Fa mqdes +argument is not a valid message queue descriptor open for reading. +.It Bq Er EMSGSIZE +The specified message buffer size, +.Fa msg_len , +is less than the message size attribute of the message queue. +.It Bq Er EINTR +The +.Fn mq_receive +or +.Fn mq_timedreceive +operation was interrupted by a signal. +.It Bq Er EINVAL +The process or thread would have blocked, and the +.Fa abs_timeout +parameter specified a nanoseconds field value less than zero or greater +than or equal to 1000 million. +.It Bq Er ETIMEDOUT +The +.Dv O_NONBLOCK +flag was not set when the message queue was opened, but no message arrived +on the queue before the specified timeout expired. +.El +.Sh SEE ALSO +.Xr mq_open 2 , +.Xr mq_send 2 , +.Xr mq_timedsend 2 +.Sh STANDARDS +The +.Fn mq_receive +and +.Fn mq_timedreceive +system calls conform to +.St -p1003.1-2004 . +.Sh HISTORY +Support for +.Tn POSIX +message queues first appeared in +.Fx 7.0 . +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard is +the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html. diff --git a/lib/libsys/mq_send.2 b/lib/libsys/mq_send.2 new file mode 100644 index 000000000000..8688f2742a94 --- /dev/null +++ b/lib/libsys/mq_send.2 @@ -0,0 +1,234 @@ +.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org> +.\" All rights reserved. +.\" +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.Dd November 29, 2005 +.Dt MQ_SEND 2 +.Os +.Sh NAME +.Nm mq_send , mq_timedsend +.Nd "send a message to message queue (REALTIME)" +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft int +.Fo mq_send +.Fa "mqd_t mqdes" +.Fa "const char *msg_ptr" +.Fa "size_t msg_len" +.Fa "unsigned msg_prio" +.Fc +.Ft int +.Fo mq_timedsend +.Fa "mqd_t mqdes" +.Fa "const char *msg_ptr" +.Fa "size_t msg_len" +.Fa "unsigned msg_prio" +.Fa "const struct timespec *abs_timeout" +.Fc +.Sh DESCRIPTION +The +.Fn mq_send +system call adds the message pointed to by the argument +.Fa msg_ptr +to the message queue specified by +.Fa mqdes . +The +.Fa msg_len +argument specifies the length of the message, in bytes, pointed to by +.Fa msg_ptr . +The value of +.Fa msg_len +should be less than or equal to the +.Va mq_msgsize +attribute of the message queue, or +.Fn mq_send +will fail. +.Pp +If the specified message queue is not full, +.Fn mq_send +will behave as if the message is inserted into the message queue at +the position indicated by the +.Fa msg_prio +argument. +A message with a larger numeric value of +.Fa msg_prio +will be inserted before messages with lower values of +.Fa msg_prio . +A message will be inserted after other messages in the queue, if any, +with equal +.Fa msg_prio . +The value of +.Fa msg_prio +should be less than +.Brq Dv MQ_PRIO_MAX . +.Pp +If the specified message queue is full and +.Dv O_NONBLOCK +is not set in the message queue description associated with +.Fa mqdes , +.Fn mq_send +will block until space becomes available to enqueue the +message, or until +.Fn mq_send +is interrupted by a signal. +If more than one thread is +waiting to send when space becomes available in the message queue and +the Priority Scheduling option is supported, then the thread of the +highest priority that has been waiting the longest will be unblocked +to send its message. +Otherwise, it is unspecified which waiting thread +is unblocked. +If the specified message queue is full and +.Dv O_NONBLOCK +is set in the message queue description associated with +.Fa mqdes , +the message will not be queued and +.Fn mq_send +will return an error. +.Pp +The +.Fn mq_timedsend +system call will add a message to the message queue specified by +.Fa mqdes +in the manner defined for the +.Fn mq_send +system call. +However, if the specified message queue is full and +.Dv O_NONBLOCK +is not set in the message queue description associated with +.Fa mqdes , +the wait for sufficient room in the queue will be terminated when +the specified timeout expires. +If +.Dv O_NONBLOCK +is set in the message queue description, this system call is +equivalent to +.Fn mq_send . +.Pp +The timeout will expire when the absolute time specified by +.Fa abs_timeout +passes, as measured by the clock on which timeouts are based (that is, +when the value of that clock equals or exceeds +.Fa abs_timeout ) , +or if the absolute time specified by +.Fa abs_timeout +has already been passed at the time of the call. +.Pp +The timeout is based on the +.Dv CLOCK_REALTIME +clock. +.Sh RETURN VALUES +Upon successful completion, the +.Fn mq_send +and +.Fn mq_timedsend +system calls return a value of zero. +Otherwise, no message will be +enqueued, the system calls return \-1, and +the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn mq_send +and +.Fn mq_timedsend +system calls +will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The +.Dv O_NONBLOCK +flag is set in the message queue description associated with +.Fa mqdes , +and the specified message queue is full. +.It Bq Er EBADF +The +.Fa mqdes +argument is not a valid message queue descriptor open for writing. +.It Bq Er EINTR +A signal interrupted the call to +.Fn mq_send +or +.Fn mq_timedsend . +.It Bq Er EINVAL +The value of +.Fa msg_prio +was outside the valid range. +.It Bq Er EINVAL +The process or thread would have blocked, and the +.Fa abs_timeout +parameter specified a nanoseconds field value less than zero or greater +than or equal to 1000 million. +.It Bq Er EMSGSIZE +The specified message length, +.Fa msg_len , +exceeds the message size attribute of the message queue. +.It Bq Er ETIMEDOUT +The +.Dv O_NONBLOCK +flag was not set when the message queue was opened, but the timeout +expired before the message could be added to the queue. +.El +.Sh SEE ALSO +.Xr mq_open 2 , +.Xr mq_receive 2 , +.Xr mq_setattr 2 , +.Xr mq_timedreceive 2 +.Sh STANDARDS +The +.Fn mq_send +and +.Fn mq_timedsend +system calls conform to +.St -p1003.1-2004 . +.Sh HISTORY +Support for +.Tn POSIX +message queues first appeared in +.Fx 7.0 . +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard is +the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html. diff --git a/lib/libsys/mq_setattr.2 b/lib/libsys/mq_setattr.2 new file mode 100644 index 000000000000..30e0a607c1ea --- /dev/null +++ b/lib/libsys/mq_setattr.2 @@ -0,0 +1,121 @@ +.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org> +.\" All rights reserved. +.\" +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.Dd May 17, 2011 +.Dt MQ_SETATTR 2 +.Os +.Sh NAME +.Nm mq_setattr +.Nd "set message queue attributes (REALTIME)" +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft int +.Fo mq_setattr +.Fa "mqd_t mqdes" +.Fa "const struct mq_attr *restrict mqstat" +.Fa "struct mq_attr *restrict omqstat" +.Fc +.Sh DESCRIPTION +The +.Fn mq_setattr +system call sets attributes associated with the open message queue description +referenced by the message queue descriptor specified by +.Fa mqdes . +The message queue attributes corresponding to the following members defined +in the +.Vt mq_attr +structure will be set to the specified values upon successful completion of +.Fn mq_setattr : +.Bl -tag -width ".Va mq_flags" +.It Va mq_flags +The value of this member is zero or +.Dv O_NONBLOCK . +.El +.Pp +The values of the +.Va mq_maxmsg , mq_msgsize , +and +.Va mq_curmsgs +members of the +.Vt mq_attr +structure are ignored by +.Fn mq_setattr . +.Sh RETURN VALUES +Upon successful completion, the function returns a value of zero and the +attributes of the message queue will have been changed as specified. +.Pp +Otherwise, the message queue attributes are unchanged, and the function +returns a value of \-1 and sets the global variable +.Va errno +to indicate the error. +.Sh ERRORS +The +.Fn mq_setattr +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa mqdes +argument is not a valid message queue descriptor. +.El +.Sh SEE ALSO +.Xr mq_open 2 , +.Xr mq_send 2 , +.Xr mq_timedsend 2 +.Sh STANDARDS +The +.Fn mq_setattr +system call conforms to +.St -p1003.1-2004 . +.Sh HISTORY +Support for +.Tn POSIX +message queues first appeared in +.Fx 7.0 . +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard is +the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html. diff --git a/lib/libsys/mq_unlink.2 b/lib/libsys/mq_unlink.2 new file mode 100644 index 000000000000..1bc74b85524f --- /dev/null +++ b/lib/libsys/mq_unlink.2 @@ -0,0 +1,119 @@ +.\" Copyright (c) 2021 Fernando Apesteguia <fernape@FreeBSD.org> +.\" +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.Dd February 15, 2021 +.Dt MQ_UNLINK 2 +.Os +.Sh NAME +.Nm mq_unlink +.Nd "mq_unlink - remove a message queue (REALTIME)" +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft int +.Fn mq_unlink "const char *name" +.Sh DESCRIPTION +The +.Fn mq_unlink +function removes the message queue named by the string +.Fa name . +If one or more processes have the message queue open when +.Fn mq_unlink +is called, destruction of the message queue will be postponed +until all references to the message queue have been closed. +However, the +.Fn mq_unlink +call need not block until all references have been closed; it may return +immediately. +.Pp +After a successful call to +.Fn mq_unlink , +reuse of the name will subsequently cause +.Xr mq_open 2 +to behave as if no message queue of this name exists. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn mq_unlink +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EACCESS +Permission is denied to unlink the message queue represented by +.Fa name . +.It Bq Er EINVAL +.Fa name +is invalid. +.It Bq Er ENAMETOOLONG +The length of the +.Fa name +argument exceeds +.Brq Dv PATH_MAX +or +a pathname component is longer than +.Brq Dv NAME_MAX . +.It Bq Er ENOENT +The message queue does not exist. +.It Bq Er ENOSYS +.Xr mqueuefs 4 +module is neither loaded nor included in the kernel. +.El +.Sh SEE ALSO +.Xr mq_open 2 +.Sh STANDARDS +The +.Fn mq_unlink +system call conforms to +.St -p1003.1-2004 . +The +.Bq Er EACCESS +error code is an extension to the standard. +.Sh HISTORY +Support for POSIX message queues first appeared in +.Fx 7.0 . +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard is +the referee document. +The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html. diff --git a/lib/libsys/msgctl.2 b/lib/libsys/msgctl.2 new file mode 100644 index 000000000000..7556aa5c5cfd --- /dev/null +++ b/lib/libsys/msgctl.2 @@ -0,0 +1,206 @@ +.\" $NetBSD: msgctl.2,v 1.1 1995/10/16 23:49:15 jtc Exp $ +.\" +.\" Copyright (c) 1995 Frank van der Linden +.\" All rights reserved. +.\" +.\" 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. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the NetBSD Project +.\" by Frank van der Linden +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 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. +.\"/ +.Dd July 9, 2020 +.Dt MSGCTL 2 +.Os +.Sh NAME +.Nm msgctl +.Nd message control operations +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/ipc.h +.In sys/msg.h +.Ft int +.Fn msgctl "int msqid" "int cmd" "struct msqid_ds *buf" +.Sh DESCRIPTION +The +.Fn msgctl +system call performs some control operations on the message queue specified +by +.Fa msqid . +.Pp +Each message queue has a data structure associated with it, parts of which +may be altered by +.Fn msgctl +and parts of which determine the actions of +.Fn msgctl . +The data structure is defined in +.In sys/msg.h +and contains (amongst others) the following members: +.Bd -literal +struct msqid_ds { + struct ipc_perm msg_perm; /* msg queue permission bits */ + msglen_t msg_cbytes; /* number of bytes in use on the queue */ + msgqnum_t msg_qnum; /* number of msgs in the queue */ + msglen_t msg_qbytes; /* max # of bytes on the queue */ + pid_t msg_lspid; /* pid of last msgsnd() */ + pid_t msg_lrpid; /* pid of last msgrcv() */ + time_t msg_stime; /* time of last msgsnd() */ + time_t msg_rtime; /* time of last msgrcv() */ + time_t msg_ctime; /* time of last msgctl() */ +}; +.Ed +.Pp +The +.Vt ipc_perm +structure used inside the +.Vt msqid_ds +structure is defined in +.In sys/ipc.h +and looks like this: +.Bd -literal +struct ipc_perm { + uid_t cuid; /* creator user id */ + gid_t cgid; /* creator group id */ + uid_t uid; /* user id */ + gid_t gid; /* group id */ + mode_t mode; /* r/w permission */ + unsigned short seq; /* sequence # (to generate unique ipcid) */ + key_t key; /* user specified msg/sem/shm key */ +}; +.Ed +.Pp +The operation to be performed by +.Fn msgctl +is specified in +.Fa cmd +and is one of: +.Bl -tag -width IPC_RMIDX +.It Dv IPC_STAT +Gather information about the message queue and place it in the +structure pointed to by +.Fa buf . +.It Dv IPC_SET +Set the value of the +.Va msg_perm.uid , +.Va msg_perm.gid , +.Va msg_perm.mode +and +.Va msg_qbytes +fields in the structure associated with +.Fa msqid . +The values are taken from the corresponding fields in the structure +pointed to by +.Fa buf . +This operation can only be executed by the super-user, or a process that +has an effective user id equal to either +.Va msg_perm.cuid +or +.Va msg_perm.uid +in the data structure associated with the message queue. +The value of +.Va msg_qbytes +can only be increased by the super-user. +Values for +.Va msg_qbytes +that exceed the system limit (MSGMNB from +.In sys/msg.h ) +are silently truncated to that limit. +.It Dv IPC_RMID +Remove the message queue specified by +.Fa msqid +and destroy the data associated with it. +Only the super-user or a process +with an effective uid equal to the +.Va msg_perm.cuid +or +.Va msg_perm.uid +values in the data structure associated with the queue can do this. +.El +.Pp +The permission to read from or write to a message queue (see +.Xr msgsnd 2 +and +.Xr msgrcv 2 ) +is determined by the +.Va msg_perm.mode +field in the same way as is +done with files (see +.Xr chmod 2 ) , +but the effective uid can match either the +.Va msg_perm.cuid +field or the +.Va msg_perm.uid +field, and the +effective gid can match either +.Va msg_perm.cgid +or +.Va msg_perm.gid . +.Sh RETURN VALUES +.Rv -std msgctl +.Sh ERRORS +The +.Fn msgctl +function +will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +The +.Fa cmd +argument +is equal to IPC_SET or IPC_RMID and the caller is not the super-user, nor does +the effective uid match either the +.Va msg_perm.uid +or +.Va msg_perm.cuid +fields of the data structure associated with the message queue. +.Pp +An attempt is made to increase the value of +.Va msg_qbytes +through IPC_SET +but the caller is not the super-user. +.It Bq Er EACCES +The command is IPC_STAT +and the caller has no read permission for this message queue. +.It Bq Er EINVAL +The +.Fa msqid +argument +is not a valid message queue identifier. +.Pp +.Va cmd +is not a valid command. +.It Bq Er EFAULT +The +.Fa buf +argument +specifies an invalid address. +.El +.Sh SEE ALSO +.Xr msgget 2 , +.Xr msgrcv 2 , +.Xr msgsnd 2 +.Sh HISTORY +Message queues appeared in the first release of +.At V . diff --git a/lib/libsys/msgget.2 b/lib/libsys/msgget.2 new file mode 100644 index 000000000000..c87f51ef57bf --- /dev/null +++ b/lib/libsys/msgget.2 @@ -0,0 +1,153 @@ +.\" $NetBSD: msgget.2,v 1.1 1995/10/16 23:49:19 jtc Exp $ +.\" +.\" Copyright (c) 1995 Frank van der Linden +.\" All rights reserved. +.\" +.\" 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. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the NetBSD Project +.\" by Frank van der Linden +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 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. +.\" +.\"/ +.Dd March 4, 2018 +.Dt MSGGET 2 +.Os +.Sh NAME +.Nm msgget +.Nd get message queue +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/msg.h +.Ft int +.Fn msgget "key_t key" "int msgflg" +.Sh DESCRIPTION +The +.Fn msgget +function +returns the message queue identifier associated with +.Fa key . +A message queue identifier is a unique integer greater than zero. +.Pp +A message queue is created if either +.Fa key +is equal to +.Dv IPC_PRIVATE , +or +.Fa key +does not have a message queue identifier associated with it, and the +.Dv IPC_CREAT +bit is set in +.Fa msgflg . +.Pp +If a new message queue is created, the data structure associated with it (the +.Va msqid_ds +structure, see +.Xr msgctl 2 ) +is initialized as follows: +.Bl -bullet +.It +.Va msg_perm.cuid +and +.Va msg_perm.uid +are set to the effective uid of the calling process. +.It +.Va msg_perm.gid +and +.Va msg_perm.cgid +are set to the effective gid of the calling process. +.It +.Va msg_perm.mode +is set to the lower 9 bits of +.Fa msgflg +which are set by ORing these constants: +.Bl -tag -width 0000 +.It Dv 0400 +Read access for user. +.It Dv 0200 +Write access for user. +.It Dv 0040 +Read access for group. +.It Dv 0020 +Write access for group. +.It Dv 0004 +Read access for other. +.It Dv 0002 +Write access for other. +.El +.It +.Va msg_cbytes , +.Va msg_qnum , +.Va msg_lspid , +.Va msg_lrpid , +.Va msg_rtime , +and +.Va msg_stime +are set to 0. +.It +.Va msg_qbytes +is set to the system wide maximum value for the number of bytes in a queue +.Pf ( Dv MSGMNB ) . +.It +.Va msg_ctime +is set to the current time. +.El +.Sh RETURN VALUES +Upon successful completion a positive message queue identifier is returned. +Otherwise, -1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EACCES +A message queue is already associated with +.Fa key +and the caller has no permission to access it. +.It Bq Er EEXIST +Both +.Dv IPC_CREAT +and +.Dv IPC_EXCL +are set in +.Fa msgflg , +and a message queue is already associated with +.Fa key . +.It Bq Er ENOSPC +A new message queue could not be created because the system limit for +the number of message queues has been reached. +.It Bq Er ENOENT +.Dv IPC_CREAT +was not set in +.Fa msgflg +and no message queue associated with +.Fa key +was found. +.El +.Sh SEE ALSO +.Xr msgctl 2 , +.Xr msgrcv 2 , +.Xr msgsnd 2 +.Sh HISTORY +Message queues appeared in the first release of +.At V . diff --git a/lib/libsys/msgrcv.2 b/lib/libsys/msgrcv.2 new file mode 100644 index 000000000000..d8ca6626d63b --- /dev/null +++ b/lib/libsys/msgrcv.2 @@ -0,0 +1,221 @@ +.\" $NetBSD: msgrcv.2,v 1.1 1995/10/16 23:49:20 jtc Exp $ +.\" +.\" Copyright (c) 1995 Frank van der Linden +.\" All rights reserved. +.\" +.\" 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. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the NetBSD Project +.\" by Frank van der Linden +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 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. +.\" +.\"/ +.Dd July 28, 2016 +.Dt MSGRCV 2 +.Os +.Sh NAME +.Nm msgrcv +.Nd receive a message from a message queue +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/ipc.h +.In sys/msg.h +.Ft ssize_t +.Fn msgrcv "int msqid" "void *msgp" "size_t msgsz" "long msgtyp" "int msgflg" +.Sh DESCRIPTION +The +.Fn msgrcv +function receives a message from the message queue specified in +.Fa msqid , +and places it into the structure pointed to by +.Fa msgp . +This structure should consist of the following members: +.Bd -literal + long mtype; /* message type */ + char mtext[1]; /* body of message */ +.Ed +.Pp +.Va mtype +is an integer greater than 0 that can be used for selecting messages, +.Va mtext +is an array of bytes, with a size up to that of the system limit +.Pf ( Dv MSGMAX ) . +.Pp +The value of +.Fa msgtyp +has one of the following meanings: +.Bl -bullet +.It +The +.Fa msgtyp +argument +is greater than 0. +The first message of type +.Fa msgtyp +will be received. +.It +The +.Fa msgtyp +argument +is equal to 0. +The first message on the queue will be received. +.It +The +.Fa msgtyp +argument +is less than 0. +The first message of the lowest message type that is +less than or equal to the absolute value of +.Fa msgtyp +will be received. +.El +.Pp +The +.Fa msgsz +argument +specifies the maximum length of the requested message. +If the received +message has a length greater than +.Fa msgsz +it will be silently truncated if the +.Dv MSG_NOERROR +flag is set in +.Fa msgflg , +otherwise an error will be returned. +.Pp +If no matching message is present on the message queue specified by +.Fa msqid , +the behavior of +.Fn msgrcv +depends on whether the +.Dv IPC_NOWAIT +flag is set in +.Fa msgflg +or not. +If +.Dv IPC_NOWAIT +is set, +.Fn msgrcv +will immediately return a value of -1, and set +.Va errno +to +.Er ENOMSG . +If +.Dv IPC_NOWAIT +is not set, the calling process will be blocked +until: +.Bl -bullet +.It +A message of the requested type becomes available on the message queue. +.It +The message queue is removed, in which case -1 will be returned, and +.Va errno +set to +.Er EINVAL . +.It +A signal is received and caught. +-1 is returned, and +.Va errno +set to +.Er EINTR . +.El +.Pp +If a message is successfully received, the data structure associated with +.Fa msqid +is updated as follows: +.Bl -bullet +.It +.Va msg_cbytes +is decremented by the size of the message. +.It +.Va msg_lrpid +is set to the pid of the caller. +.It +.Va msg_lrtime +is set to the current time. +.It +.Va msg_qnum +is decremented by 1. +.El +.Sh RETURN VALUES +Upon successful completion, +.Fn msgrcv +returns the number of bytes received into the +.Va mtext +field of the structure pointed to by +.Fa msgp . +Otherwise, -1 is returned, and +.Va errno +set to indicate the error. +.Sh ERRORS +The +.Fn msgrcv +function +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa msqid +argument +is not a valid message queue identifier. +.Pp +The message queue was removed while +.Fn msgrcv +was waiting for a message of the requested type to become available on it. +.Pp +The +.Fa msgsz +argument +is less than 0. +.It Bq Er E2BIG +A matching message was received, but its size was greater than +.Fa msgsz +and the +.Dv MSG_NOERROR +flag was not set in +.Fa msgflg . +.It Bq Er EACCES +The calling process does not have read access to the message queue. +.It Bq Er EFAULT +The +.Fa msgp +argument +points to an invalid address. +.It Bq Er EINTR +The system call was interrupted by the delivery of a signal. +.It Bq Er ENOMSG +There is no message of the requested type available on the message queue, +and +.Dv IPC_NOWAIT +is set in +.Fa msgflg . +.El +.Sh SEE ALSO +.Xr msgctl 2 , +.Xr msgget 2 , +.Xr msgsnd 2 +.Sh HISTORY +Message queues appeared in the first release of +.At V . diff --git a/lib/libsys/msgsnd.2 b/lib/libsys/msgsnd.2 new file mode 100644 index 000000000000..9677c80dc939 --- /dev/null +++ b/lib/libsys/msgsnd.2 @@ -0,0 +1,182 @@ +.\" $NetBSD: msgsnd.2,v 1.1 1995/10/16 23:49:24 jtc Exp $ +.\" +.\" Copyright (c) 1995 Frank van der Linden +.\" All rights reserved. +.\" +.\" 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. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the NetBSD Project +.\" by Frank van der Linden +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 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. +.\" +.Dd July 9, 2009 +.Dt MSGSND 2 +.Os +.Sh NAME +.Nm msgsnd +.Nd send a message to a message queue +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/ipc.h +.In sys/msg.h +.Ft int +.Fn msgsnd "int msqid" "const void *msgp" "size_t msgsz" "int msgflg" +.Sh DESCRIPTION +The +.Fn msgsnd +function sends a message to the message queue specified in +.Fa msqid . +The +.Fa msgp +argument +points to a structure containing the message. +This structure should +consist of the following members: +.Bd -literal + long mtype; /* message type */ + char mtext[1]; /* body of message */ +.Ed +.Pp +.Va mtype +is an integer greater than 0 that can be used for selecting messages (see +.Xr msgrcv 2 ) , +.Va mtext +is an array of +.Fa msgsz +bytes. +The argument +.Fa msgsz +can range from 0 to a system-imposed maximum, +.Dv MSGMAX . +.Pp +If the number of bytes already on the message queue plus +.Fa msgsz +is bigger than the maximum number of bytes on the message queue +.Pf ( Va msg_qbytes , +see +.Xr msgctl 2 ) , +or the number of messages on all queues system-wide is already equal to +the system limit, +.Fa msgflg +determines the action of +.Fn msgsnd . +If +.Fa msgflg +has +.Dv IPC_NOWAIT +mask set in it, the call will return immediately. +If +.Fa msgflg +does not have +.Dv IPC_NOWAIT +set in it, the call will block until: +.Bl -bullet +.It +The condition which caused the call to block does no longer exist. +The message will be sent. +.It +The message queue is removed, in which case -1 will be returned, and +.Va errno +is set to +.Er EINVAL . +.It +The caller catches a signal. +The call returns with +.Va errno +set to +.Er EINTR . +.El +.Pp +After a successful call, the data structure associated with the message +queue is updated in the following way: +.Bl -bullet +.It +.Va msg_cbytes +is incremented by the size of the message. +.It +.Va msg_qnum +is incremented by 1. +.It +.Va msg_lspid +is set to the pid of the calling process. +.It +.Va msg_stime +is set to the current time. +.El +.Sh RETURN VALUES +.Rv -std msgsnd +.Sh ERRORS +The +.Fn msgsnd +function +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa msqid +argument +is not a valid message queue identifier. +.Pp +The message queue was removed while +.Fn msgsnd +was waiting for a resource to become available in order to deliver the +message. +.Pp +The +.Fa msgsz +argument +is greater than +.Va msg_qbytes . +.Pp +The +.Fa mtype +argument +is not greater than 0. +.It Bq Er EACCES +The calling process does not have write access to the message queue. +.It Bq Er EAGAIN +There was no space for this message either on the queue, or in the whole +system, and +.Dv IPC_NOWAIT +was set in +.Fa msgflg . +.It Bq Er EFAULT +The +.Fa msgp +argument +points to an invalid address. +.It Bq Er EINTR +The system call was interrupted by the delivery of a signal. +.El +.Sh HISTORY +Message queues appeared in the first release of AT&T Unix System V. +.Sh BUGS +.Nx +and +.Fx +do not define the +.Er EIDRM +error value, which should be used +in the case of a removed message queue. diff --git a/lib/libsys/msync.2 b/lib/libsys/msync.2 new file mode 100644 index 000000000000..3e10a2835bc8 --- /dev/null +++ b/lib/libsys/msync.2 @@ -0,0 +1,123 @@ +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd March 18, 2012 +.Dt MSYNC 2 +.Os +.Sh NAME +.Nm msync +.Nd synchronize a mapped region +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/mman.h +.Ft int +.Fn msync "void *addr" "size_t len" "int flags" +.Sh DESCRIPTION +The +.Fn msync +system call +writes any modified pages back to the file system and updates +the file modification time. +If +.Fa len +is 0, all modified pages within the region containing +.Fa addr +will be flushed; +if +.Fa len +is non-zero, only those pages containing +.Fa addr +and +.Fa len-1 +succeeding locations will be examined. +The +.Fa flags +argument may be specified as follows: +.Pp +.Bl -tag -width ".Dv MS_INVALIDATE" -compact +.It Dv MS_ASYNC +Return immediately +.It Dv MS_SYNC +Perform synchronous writes +.It Dv MS_INVALIDATE +Invalidate all cached data +.El +.Sh RETURN VALUES +.Rv -std msync +.Sh ERRORS +The +.Fn msync +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +Some or all of the pages in the specified region are locked and +.Dv MS_INVALIDATE +is specified. +.It Bq Er EINVAL +The +.Fa addr +argument +is not a multiple of the hardware page size. +.It Bq Er ENOMEM +The addresses in the range starting at +.Fa addr +and continuing for +.Fa len +bytes are outside the range allowed for the address space of a +process or specify one or more pages that are not mapped. +.It Bq Er EINVAL +The +.Fa flags +argument +was both MS_ASYNC and MS_INVALIDATE. +Only one of these flags is allowed. +.It Bq Er EIO +An error occurred while writing at least one of the pages in +the specified region. +.El +.Sh SEE ALSO +.Xr madvise 2 , +.Xr mincore 2 , +.Xr mlock 2 , +.Xr mprotect 2 , +.Xr munmap 2 +.Sh HISTORY +The +.Fn msync +system call first appeared in +.Bx 4.4 . +.Sh BUGS +The +.Fn msync +system call is usually not needed since +.Bx +implements a coherent file system buffer cache. +However, it may be used to associate dirty VM pages with file system +buffers and thus cause them to be flushed to physical media sooner +rather than later. diff --git a/lib/libsys/munmap.2 b/lib/libsys/munmap.2 new file mode 100644 index 000000000000..5c587d652a42 --- /dev/null +++ b/lib/libsys/munmap.2 @@ -0,0 +1,82 @@ +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd January 16, 2025 +.Dt MUNMAP 2 +.Os +.Sh NAME +.Nm munmap +.Nd remove a mapping +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/mman.h +.Ft int +.Fn munmap "void *addr" "size_t len" +.Sh DESCRIPTION +The +.Fn munmap +system call +deletes the mappings and guards for the specified address range, +and causes further references to addresses within the range +to generate invalid memory references. +.Sh RETURN VALUES +.Rv -std munmap +.Sh ERRORS +The +.Fn munmap +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa len +argument was zero, or +some part of the region being unmapped is outside the +valid address range for a process. +.El +.Sh "SEE ALSO" +.Xr madvise 2 , +.Xr mincore 2 , +.Xr mmap 2 , +.Xr mprotect 2 , +.Xr msync 2 , +.Xr getpagesize 3 +.Sh STANDARDS +The +.Fn munmap +system call conforms to +.St -p1003.1-2024 . +Portable programs should ensure that +.Fa addr +is a multiple of the page size as returned by +.Xr sysconf 3 . +.Sh HISTORY +The +.Fn munmap +system call first appeared in +.Bx 4.4 . diff --git a/lib/libsys/nanosleep.2 b/lib/libsys/nanosleep.2 new file mode 100644 index 000000000000..290565dbd6e1 --- /dev/null +++ b/lib/libsys/nanosleep.2 @@ -0,0 +1,255 @@ +.\" $NetBSD: nanosleep.2,v 1.23 2016/11/14 10:40:59 wiz Exp $ +.\" +.\" Copyright (c) 1986, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd May 3, 2025 +.Dt NANOSLEEP 2 +.Os +.Sh NAME +.Nm nanosleep +.Nd high resolution sleep +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In time.h +.Ft int +.Fo clock_nanosleep +.Fa "clockid_t clock_id" +.Fa "int flags" +.Fa "const struct timespec *rqtp" +.Fa "struct timespec *rmtp" +.Fc +.Ft int +.Fo nanosleep +.Fa "const struct timespec *rqtp" +.Fa "struct timespec *rmtp" +.Fc +.Sh DESCRIPTION +If the +.Dv TIMER_ABSTIME +flag is not set in the +.Fa flags +argument, then +.Fn clock_nanosleep +suspends execution of the calling thread until either the +time interval specified by the +.Fa rqtp +argument has elapsed, +or a signal is delivered to the calling process and its +action is to invoke a signal-catching function or to terminate the +process. +The clock used to measure the time is specified by the +.Fa clock_id +argument. +.Pp +If the +.Dv TIMER_ABSTIME +flag is set in the +.Fa flags +argument, then +.Fn clock_nanosleep +suspends execution of the calling thread until either the value +of the clock specified by the +.Fa clock_id +argument reaches the absolute time specified by the +.Fa rqtp +argument, +or a signal is delivered to the calling process and its +action is to invoke a signal-catching function or to terminate the +process. +If, at the time of the call, the time value specified by +.Fa rqtp +is less than or equal to the time value of the specified clock, then +.Fn clock_nanosleep +returns immediately and the calling thread is not suspended. +An unmasked signal will terminate the sleep early, regardless of the +.Dv SA_RESTART +value on the interrupting signal. +The +.Fa rqtp +and +.Fa rmtp +arguments can point to the same object. +.Pp +The following +.Fa clock_id +values are supported: +.Pp +.Bl -item -compact -offset indent +.It +CLOCK_MONOTONIC +.It +CLOCK_MONOTONIC_FAST +.It +CLOCK_MONOTONIC_PRECISE +.It +CLOCK_REALTIME +.It +CLOCK_REALTIME_FAST +.It +CLOCK_REALTIME_PRECISE +.It +CLOCK_SECOND +.It +CLOCK_TAI +.It +CLOCK_UPTIME +.It +CLOCK_UPTIME_FAST +.It +CLOCK_UPTIME_PRECISE +.El +.Pp +The suspension time may be longer than requested due to the +scheduling of other activity by the system. +The clocks with the +.Dv _FAST +suffix and the +.Dv CLOCK_SECOND +are subject to the allowed time interval deviation specified by the +.Va kern.timecounter.alloweddeviation +.Xr sysctl 8 +variable. +The clocks with the +.Dv _PRECISE +suffix are always as precise as possible. +The +.Dv CLOCK_MONOTONIC , +.Dv CLOCK_REALTIME +and +.Dv CLOCK_UPTIME +are precise by default. +Setting the +.Va kern.timecounter.nanosleep_precise +.Xr sysctl 8 +to a false value would make those clocks to behave like the +.Dv _FAST +clocks. +.Pp +The +.Fn nanosleep +function behaves like +.Fn clock_nanosleep +with a +.Fa clock_id +argument of +.Dv CLOCK_REALTIME +and without the +.Dv TIMER_ABSTIME +flag in the +.Fa flags +argument. +.Sh RETURN VALUES +These functions return zero when the requested time has elapsed. +.Pp +If these functions return for any other reason, then +.Fn clock_nanosleep +will directly return the error number, and +.Fn nanosleep +will return \-1 with the global variable +.Va errno +set to indicate the error. +If a relative sleep is interrupted by a signal and +.Fa rmtp +is +.Pf non- Dv NULL , +the timespec structure it references is updated to contain the +unslept amount (the request time minus the time actually slept). +.Sh ERRORS +These functions can fail with the following errors. +.Bl -tag -width Er +.It Bq Er EFAULT +Either +.Fa rqtp +or +.Fa rmtp +points to memory that is not a valid part of the process +address space. +.It Bq Er EINTR +The function was interrupted by the delivery of a signal. +.It Bq Er EINVAL +The +.Fa rqtp +argument specified a nanosecond value less than zero +or greater than or equal to 1000 million. +.It Bq Er EINVAL +The +.Fa flags +argument contained an invalid flag. +.It Bq Er EINVAL +The +.Fa clock_id +argument was +.Dv CLOCK_THREAD_CPUTIME_ID +or an unrecognized value. +.It Bq Er ENOTSUP +The +.Fa clock_id +argument was valid but not supported by this implementation of +.Fn clock_nanosleep . +.El +.Sh SEE ALSO +.Xr clock_gettime 2 , +.Xr sigaction 2 , +.Xr sleep 3 +.Sh STANDARDS +These functions conform to +.St -p1003.1-2008 . +.Sh HISTORY +The predecessor of this system call, +.Fn sleep , +appeared in +.At v3 , +but was removed when +.Xr alarm 3 +was introduced into +.At v7 . +The +.Fn nanosleep +system call has been available since +.Nx 1.3 +and was ported to +.Ox 2.1 +and +.Fx 3.0 . +The +.Fn clock_nanosleep +system call has been available since +.Fx 11.1 . +.Pp +In +.Fx 15.0 +the default behavior of +.Fn clock_nanosleep +with +.Dv CLOCK_MONOTONIC , +.Dv CLOCK_REALTIME , +.Dv CLOCK_UPTIME +clocks and +.Fn nanosleep +has been switched to use precise clock. diff --git a/lib/libsys/nfssvc.2 b/lib/libsys/nfssvc.2 new file mode 100644 index 000000000000..9a0b2e020b91 --- /dev/null +++ b/lib/libsys/nfssvc.2 @@ -0,0 +1,255 @@ +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd June 9, 1993 +.Dt NFSSVC 2 +.Os +.Sh NAME +.Nm nfssvc +.Nd NFS services +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.In sys/time.h +.In nfs/rpcv2.h +.In nfsserver/nfs.h +.In unistd.h +.Ft int +.Fn nfssvc "int flags" "void *argstructp" +.Sh DESCRIPTION +The +.Fn nfssvc +system call is used by the NFS daemons to pass information into and out +of the kernel and also to enter the kernel as a server daemon. +The +.Fa flags +argument consists of several bits that show what action is to be taken +once in the kernel and the +.Fa argstructp +points to one of three structures depending on which bits are set in +flags. +.Pp +On the client side, +.Xr nfsiod 8 +calls +.Fn nfssvc +with the +.Fa flags +argument set to +.Dv NFSSVC_BIOD +and +.Fa argstructp +set to +.Dv NULL +to enter the kernel as a block I/O server daemon. +For +.Tn NQNFS , +.Xr mount_nfs 8 +calls +.Fn nfssvc +with the +.Dv NFSSVC_MNTD +flag, optionally or'd with the flags +.Dv NFSSVC_GOTAUTH +and +.Dv NFSSVC_AUTHINFAIL +along with a pointer to a +.Bd -literal +struct nfsd_cargs { + char *ncd_dirp; /* Mount dir path */ + uid_t ncd_authuid; /* Effective uid */ + int ncd_authtype; /* Type of authenticator */ + int ncd_authlen; /* Length of authenticator string */ + u_char *ncd_authstr; /* Authenticator string */ + int ncd_verflen; /* and the verifier */ + u_char *ncd_verfstr; + NFSKERBKEY_T ncd_key; /* Session key */ +}; +.Ed +.Pp +structure. +The initial call has only the +.Dv NFSSVC_MNTD +flag set to specify service for the mount point. +If the mount point is using Kerberos, then the +.Xr mount_nfs 8 +utility will return from +.Fn nfssvc +with +.Va errno +== +.Er ENEEDAUTH +whenever the client side requires an ``rcmd'' +authentication ticket for the user. +The +.Xr mount_nfs 8 +utility will attempt to get the Kerberos ticket, and if successful will call +.Fn nfssvc +with the flags +.Dv NFSSVC_MNTD +and +.Dv NFSSVC_GOTAUTH +after filling the ticket into the +ncd_authstr field +and +setting the ncd_authlen and ncd_authtype +fields of the nfsd_cargs structure. +If +.Xr mount_nfs 8 +failed to get the ticket, +.Fn nfssvc +will be called with the flags +.Dv NFSSVC_MNTD , +.Dv NFSSVC_GOTAUTH +and +.Dv NFSSVC_AUTHINFAIL +to denote a failed authentication attempt. +.Pp +On the server side, +.Fn nfssvc +is called with the flag +.Dv NFSSVC_NFSD +and a pointer to a +.Bd -literal +struct nfsd_srvargs { + struct nfsd *nsd_nfsd; /* Pointer to in kernel nfsd struct */ + uid_t nsd_uid; /* Effective uid mapped to cred */ + uint32_t nsd_haddr; /* Ip address of client */ + struct ucred nsd_cr; /* Cred. uid maps to */ + int nsd_authlen; /* Length of auth string (ret) */ + u_char *nsd_authstr; /* Auth string (ret) */ + int nsd_verflen; /* and the verifier */ + u_char *nsd_verfstr; + struct timeval nsd_timestamp; /* timestamp from verifier */ + uint32_t nsd_ttl; /* credential ttl (sec) */ + NFSKERBKEY_T nsd_key; /* Session key */ +}; +.Ed +.Pp +to enter the kernel as an +.Xr nfsd 8 +daemon. +Whenever an +.Xr nfsd 8 +daemon receives a Kerberos authentication ticket, it will return from +.Fn nfssvc +with +.Va errno +== +.Er ENEEDAUTH . +The +.Xr nfsd 8 +utility will attempt to authenticate the ticket and generate a set of credentials +on the server for the ``user id'' specified in the field nsd_uid. +This is done by first authenticating the Kerberos ticket and then mapping +the Kerberos principal to a local name and getting a set of credentials for +that user via +.Xr getpwnam 3 +and +.Xr getgrouplist 3 . +If successful, the +.Xr nfsd 8 +utility will call +.Fn nfssvc +with the +.Dv NFSSVC_NFSD +and +.Dv NFSSVC_AUTHIN +flags set to pass the credential mapping in nsd_cr into the +kernel to be cached on the server socket for that client. +If the authentication failed, +.Xr nfsd 8 +calls +.Fn nfssvc +with the flags +.Dv NFSSVC_NFSD +and +.Dv NFSSVC_AUTHINFAIL +to denote an authentication failure. +.Pp +The master +.Xr nfsd 8 +server daemon calls +.Fn nfssvc +with the flag +.Dv NFSSVC_ADDSOCK +and a pointer to a +.Bd -literal +struct nfsd_args { + int sock; /* Socket to serve */ + caddr_t name; /* Client address for connection based sockets */ + int namelen;/* Length of name */ +}; +.Ed +.Pp +to pass a server side +.Tn NFS +socket into the kernel for servicing by the +.Xr nfsd 8 +daemons. +.Sh RETURN VALUES +Normally +.Fn nfssvc +does not return unless the server +is terminated by a signal when a value of 0 is returned. +Otherwise, -1 is returned and the global variable +.Va errno +is set to specify the error. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ENEEDAUTH +This special error value +is really used for authentication support, particularly Kerberos, +as explained above. +.It Bq Er EPERM +The caller is not the super-user. +.El +.Sh SEE ALSO +.Xr mount_nfs 8 , +.Xr nfsd 8 , +.Xr nfsiod 8 +.Sh HISTORY +The +.Fn nfssvc +system call first appeared in +.Bx 4.4 . +.Sh BUGS +The +.Fn nfssvc +system call is designed specifically for the +.Tn NFS +support daemons and as such is specific to their requirements. +It should really return values to indicate the need for authentication +support, since +.Er ENEEDAUTH +is not really an error. +Several fields of the argument structures are assumed to be valid and +sometimes to be unchanged from a previous call, such that +.Fn nfssvc +must be used with extreme care. diff --git a/lib/libsys/ntp_adjtime.2 b/lib/libsys/ntp_adjtime.2 new file mode 100644 index 000000000000..5be5194a9c1d --- /dev/null +++ b/lib/libsys/ntp_adjtime.2 @@ -0,0 +1,313 @@ +.\" $NetBSD: ntp_adjtime.2,v 1.6 2003/04/16 13:34:55 wiz Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Thomas Klausner. +.\" +.\" 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. +.\" +.Dd July 13, 2005 +.Dt NTP_ADJTIME 2 +.Os +.Sh NAME +.Nm ntp_adjtime , +.Nm ntp_gettime +.Nd Network Time Protocol (NTP) daemon interface system calls +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/timex.h +.Ft int +.Fn ntp_adjtime "struct timex *" +.Ft int +.Fn ntp_gettime "struct ntptimeval *" +.Sh DESCRIPTION +The two system calls +.Fn ntp_adjtime +and +.Fn ntp_gettime +are the kernel interface to the Network Time Protocol (NTP) daemon +.Xr ntpd 8 . +.Pp +The +.Fn ntp_adjtime +function is used by the NTP daemon to adjust the system clock to an +externally derived time. +The time offset and related variables which are set by +.Fn ntp_adjtime +are used by +.Fn hardclock +to adjust the phase and frequency of the phase- or frequency-lock loop +(PLL resp. FLL) which controls the system clock. +.Pp +The +.Fn ntp_gettime +function provides the time, maximum error (sync distance) and +estimated error (dispersion) to client user application programs. +.Pp +In the following, all variables that refer PPS are only relevant if +the +.Em PPS_SYNC +option is enabled in the kernel. +.Pp +.Fn ntp_adjtime +has as argument a +.Va struct timex * +of the following form: +.Bd -literal +struct timex { + unsigned int modes; /* clock mode bits (wo) */ + long offset; /* time offset (us) (rw) */ + long freq; /* frequency offset (scaled ppm) (rw) */ + long maxerror; /* maximum error (us) (rw) */ + long esterror; /* estimated error (us) (rw) */ + int status; /* clock status bits (rw) */ + long constant; /* pll time constant (rw) */ + long precision; /* clock precision (us) (ro) */ + long tolerance; /* clock frequency tolerance (scaled + * ppm) (ro) */ + /* + * The following read-only structure members are implemented + * only if the PPS signal discipline is configured in the + * kernel. + */ + long ppsfreq; /* pps frequency (scaled ppm) (ro) */ + long jitter; /* pps jitter (us) (ro) */ + int shift; /* interval duration (s) (shift) (ro) */ + long stabil; /* pps stability (scaled ppm) (ro) */ + long jitcnt; /* jitter limit exceeded (ro) */ + long calcnt; /* calibration intervals (ro) */ + long errcnt; /* calibration errors (ro) */ + long stbcnt; /* stability limit exceeded (ro) */ +}; +.Ed +.Pp +The members of this struct have the following meanings when used as +argument for +.Fn ntp_adjtime : +.Bl -tag -width tolerance -compact +.It Fa modes +Defines what settings should be changed with the current +.Fn ntp_adjtime +call (write-only). +Bitwise OR of the following: +.Bl -tag -width MOD_TIMECONST -compact -offset indent +.It MOD_OFFSET +set time offset +.It MOD_FREQUENCY +set frequency offset +.It MOD_MAXERROR +set maximum time error +.It MOD_ESTERROR +set estimated time error +.It MOD_STATUS +set clock status bits +.It MOD_TIMECONST +set PLL time constant +.It MOD_CLKA +set clock A +.It MOD_CLKB +set clock B +.El +.It Fa offset +Time offset (in microseconds), used by the PLL/FLL to adjust the +system time in small increments (read-write). +.It Fa freq +Frequency offset (scaled ppm) (read-write). +.It Fa maxerror +Maximum error (in microseconds). +Initialized by an +.Fn ntp_adjtime +call, and increased by the kernel once each second to reflect the maximum +error bound growth (read-write). +.It Fa esterror +Estimated error (in microseconds). +Set and read by +.Fn ntp_adjtime , +but unused by the kernel (read-write). +.It Fa status +System clock status bits (read-write). +Bitwise OR of the following: +.Bl -tag -width STA_PPSJITTER -compact -offset indent +.It STA_PLL +Enable PLL updates (read-write). +.It STA_PPSFREQ +Enable PPS freq discipline (read-write). +.It STA_PPSTIME +Enable PPS time discipline (read-write). +.It STA_FLL +Select frequency-lock mode (read-write). +.It STA_INS +Insert leap (read-write). +.It STA_DEL +Delete leap (read-write). +.It STA_UNSYNC +Clock unsynchronized (read-write). +.It STA_FREQHOLD +Hold frequency (read-write). +.It STA_PPSSIGNAL +PPS signal present (read-only). +.It STA_PPSJITTER +PPS signal jitter exceeded (read-only). +.It STA_PPSWANDER +PPS signal wander exceeded (read-only). +.It STA_PPSERROR +PPS signal calibration error (read-only). +.It STA_CLOCKERR +Clock hardware fault (read-only). +.El +.It Fa constant +PLL time constant, determines the bandwidth, or +.Dq stiffness , +of the PLL (read-write). +.It Fa precision +Clock precision (in microseconds). +In most cases the same as the kernel tick variable (see +.Xr hz 9 ) . +If a precision clock counter or external time-keeping signal is available, +it could be much lower (and depend on the state of the signal) +(read-only). +.It Fa tolerance +Maximum frequency error, or tolerance of the CPU clock oscillator (scaled +ppm). +Ordinarily a property of the architecture, but could change under +the influence of external time-keeping signals (read-only). +.It Fa ppsfreq +PPS frequency offset produced by the frequency median filter (scaled +ppm) (read-only). +.It Fa jitter +PPS jitter measured by the time median filter in microseconds +(read-only). +.It Fa shift +Logarithm to base 2 of the interval duration in seconds (PPS, +read-only). +.It Fa stabil +PPS stability (scaled ppm); dispersion (wander) measured by the +frequency median filter (read-only). +.It Fa jitcnt +Number of seconds that have been discarded because the jitter measured +by the time median filter exceeded the limit +.Em MAXTIME +(PPS, read-only). +.It Fa calcnt +Count of calibration intervals (PPS, read-only). +.It Fa errcnt +Number of calibration intervals that have been discarded because the +wander exceeded the limit +.Em MAXFREQ +or where the calibration interval jitter exceeded two ticks (PPS, +read-only). +.It Fa stbcnt +Number of calibration intervals that have been discarded because the +frequency wander exceeded the limit +.Em MAXFREQ Ns /4 +(PPS, read-only). +.El +After the +.Fn ntp_adjtime +call, the +.Va struct timex * +structure contains the current values of the corresponding variables. +.Pp +.Fn ntp_gettime +has as argument a +.Va struct ntptimeval * +with the following members: +.Bd -literal +struct ntptimeval { + struct timeval time; /* current time (ro) */ + long maxerror; /* maximum error (us) (ro) */ + long esterror; /* estimated error (us) (ro) */ +}; +.Ed +.Pp +These have the following meaning: +.Bl -tag -width tolerance -compact +.It Fa time +Current time (read-only). +.It Fa maxerror +Maximum error in microseconds (read-only). +.It Fa esterror +Estimated error in microseconds (read-only). +.El +.Sh RETURN VALUES +.Fn ntp_adjtime +and +.Fn ntp_gettime +return the current state of the clock on success, or any of the errors +of +.Xr copyin 9 +and +.Xr copyout 9 . +.Fn ntp_adjtime +may additionally return +.Er EPERM +if the user calling +.Fn ntp_adjtime +does not have sufficient permissions. +.Pp +Possible states of the clock are: +.Bl -tag -width TIME_ERROR -compact -offset indent +.It TIME_OK +Everything okay, no leap second warning. +.It TIME_INS +.Dq insert leap second +warning. +At the end of the day, a leap second will be inserted after 23:59:59. +.It TIME_DEL +.Dq delete leap second +warning. +At the end of the day, second 23:59:59 will be skipped. +.It TIME_OOP +Leap second in progress. +.It TIME_WAIT +Leap second has occurred within the last few seconds. +.It TIME_ERROR +Clock not synchronized. +.El +.Sh ERRORS +The +.Fn ntp_adjtime +system call may return +.Er EPERM +if the caller +does not have sufficient permissions. +.Sh SEE ALSO +.Xr options 4 , +.Xr ntpd 8 , +.Xr hardclock 9 , +.Xr hz 9 +.Bl -tag -width indent +.It Pa http://www.bipm.fr/enus/5_Scientific/c_time/time_1.html +.It Pa http://www.boulder.nist.gov/timefreq/general/faq.htm +.It Pa ftp://time.nist.gov/pub/leap-seconds.list +.El +.Sh BUGS +Take note that this +.Tn API +is extremely complex and stateful. +Users should not attempt modification without first +reviewing the +.Xr ntpd 8 +sources in depth. diff --git a/lib/libsys/open.2 b/lib/libsys/open.2 new file mode 100644 index 000000000000..a0e905a8f375 --- /dev/null +++ b/lib/libsys/open.2 @@ -0,0 +1,880 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd May 17, 2025 +.Dt OPEN 2 +.Os +.Sh NAME +.Nm open , openat +.Nd open or create a file for reading, writing or executing +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In fcntl.h +.Ft int +.Fn open "const char *path" "int flags" "..." +.Ft int +.Fn openat "int fd" "const char *path" "int flags" "..." +.Sh DESCRIPTION +The file name specified by +.Fa path +is opened +for either execution or reading and/or writing as specified by the +argument +.Fa flags +and the file descriptor returned to the calling process. +The +.Fa flags +argument may indicate the file is to be +created if it does not exist (by specifying the +.Dv O_CREAT +flag). +In this case +.Fn open +and +.Fn openat +require an additional argument +.Fa "mode_t mode" , +and the file is created with mode +.Fa mode +as described in +.Xr chmod 2 +and modified by the process' umask value (see +.Xr umask 2 ) . +.Pp +The +.Fn openat +function is equivalent to the +.Fn open +function except in the case where the +.Fa path +specifies a relative path. +For +.Fn openat +and relative +.Fa path , +the file to be opened is determined relative to the directory +associated with the file descriptor +.Fa fd +instead of the current working directory. +The +.Fa flag +parameter and the optional fourth parameter correspond exactly to +the parameters of +.Fn open . +If +.Fn openat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used +and the behavior is identical to a call to +.Fn open . +.Pp +When +.Fn openat +is called with an absolute +.Fa path , +it ignores the +.Fa fd +argument. +.Pp +In +.Xr capsicum 4 +capability mode, +.Fn open +is not permitted. +The +.Fa path +argument to +.Fn openat +must be strictly relative to a file descriptor +.Fa fd ; +that is, +.Fa path +must not be an absolute path and must not contain ".." components +which cause the path resolution to escape the directory hierarchy +starting at +.Fa fd . +Additionally, no symbolic link in +.Fa path +may target absolute path or contain escaping ".." components. +.Fa fd +must not be +.Dv AT_FDCWD . +.Pp +If the +.Dv vfs.lookup_cap_dotdot +.Xr sysctl 3 +MIB is set to zero, ".." components in the paths, +used in capability mode, +are completely disabled. +If the +.Dv vfs.lookup_cap_dotdot_nonlocal +MIB is set to zero, ".." is not allowed if found on non-local filesystem. +.Pp +The +.Fa flags +are formed by +.Em or Ns 'ing +the following values: +.Pp +.Bl -tag -width O_RESOLVE_BENEATH +.It Dv O_RDONLY +open for reading only +.It Dv O_WRONLY +open for writing only +.It Dv O_RDWR +open for reading and writing +.It Dv O_EXEC +open for execute only +.It Dv O_SEARCH +open for search only +(an alias for +.Dv O_EXEC +typically used with +.Dv O_DIRECTORY ) +.It Dv O_NONBLOCK +do not block on open +.It Dv O_APPEND +set file pointer to the end of the file before each write +.It Dv O_CREAT +create file if it does not exist +.It Dv O_TRUNC +truncate size to 0 +.It Dv O_EXCL +fail if +.Dv O_CREAT +is set and the file exists +.It Dv O_SHLOCK +atomically obtain a shared lock +.It Dv O_EXLOCK +atomically obtain an exclusive lock +.It Dv O_DIRECT +read and write directly from the backing store +.It Dv O_FSYNC +synchronous data and metadata writes +.Pq historical synonym for Dv O_SYNC +.It Dv O_SYNC +synchronous data and metadata writes +.It Dv O_DSYNC +synchronous data writes +.It Dv O_NOFOLLOW +do not follow symlinks +.It Dv O_NOCTTY +ignored +.It Dv O_TTY_INIT +ignored +.It Dv O_DIRECTORY +error if file is not a directory +.It Dv O_CLOEXEC +automatically close file on +.Xr execve 2 +.It Dv O_CLOFORK +automatically close file on any child process created with +.Fn fork 2 +.It Dv O_VERIFY +verify the contents of the file with +.Xr mac_veriexec 4 +.It Dv O_RESOLVE_BENEATH +.Pq Xr openat 2 only +path resolution must not cross the +.Fa fd +directory +.It Dv O_PATH +record only the target path in the opened descriptor +.It Dv O_EMPTY_PATH +.Pq Xr openat 2 only +open file referenced by +.Fa fd +if path is empty +.It Dv O_NAMEDATTR +open a named attribute or named attribute directory +.El +.Pp +Exactly one of the flags +.Dv O_RDONLY , +.Dv O_WRONLY , +.Dv O_RDWR , +or +.Dv O_EXEC +must be provided. +.Pp +Opening a file with +.Dv O_APPEND +set causes each write on the resulting file descriptor +to be appended to the end of the file. +.Pp +If +.Dv O_TRUNC +is specified and the +file exists, the file is truncated to zero length. +.Pp +If +.Dv O_CREAT +is set, but file already exists, +this flag has no effect except when +.Dv O_EXCL +is set too, in this case +.Fn open +fails with +.Er EEXIST . +This may be used to +implement a simple exclusive access locking mechanism. +In all other cases, the file is created +and the access permission bits (see +.Xr chmod 2) +of the file mode +are set to the value of the third argument taken as +.Fa "mode_t mode" +and passed through the +.Xr umask 2 . +This argument does not affect whether the file is opened +for reading, writing, or for both. +The open' request for a lock on the file, created with +.Dv O_CREAT , +will never fail +provided that the underlying file system supports locking; +see also +.Dv O_SHLOCK +and +.Dv O_EXLOCK +below. +.Pp +If +.Dv O_EXCL +is set and the last component of the pathname is +a symbolic link, +.Fn open +will fail even if the symbolic +link points to a non-existent name. +.Pp +If +.Dv O_NONBLOCK +is specified and the +.Fn open +system call would +block for some reason (for example, waiting for +carrier on a dialup line), +.Fn open +returns immediately. +The descriptor remains in non-blocking mode for subsequent operations. +.Pp +If +.Dv O_SYNC +is used in the mask, all writes will +immediately and synchronously be written to disk. +.Dv O_FSYNC +is an historical synonym for +.Dv O_SYNC . +.Pp +If +.Dv O_DSYNC +is used in the mask, all data and metadata required to read the data will be +synchronously written to disk, but changes to metadata such as file access and +modification timestamps may be written later. +.Pp +If +.Dv O_NOFOLLOW +is used in the mask and the target file passed to +.Fn open +is a symbolic link then the +.Fn open +will fail. +.Pp +When opening a file, a lock with +.Xr flock 2 +semantics can be obtained by setting +.Dv O_SHLOCK +for a shared lock, or +.Dv O_EXLOCK +for an exclusive lock. +.Pp +.Dv O_DIRECT +may be used to minimize or eliminate the cache effects of reading and writing. +The system will attempt to avoid caching the data you read or write. +If it cannot avoid caching the data, +it will minimize the impact the data has on the cache. +Use of this flag can drastically reduce performance if not used with care. +The semantics of this flag are filesystem dependent, +and some filesystems may ignore it entirely. +.Pp +.Dv O_NOCTTY +may be used to ensure the OS does not assign this file as the +controlling terminal when it opens a tty device. +This is the default on +.Fx , +but is present for +POSIX +compatibility. +The +.Fn open +system call will not assign controlling terminals on +.Fx . +.Pp +.Dv O_TTY_INIT +may be used to ensure the OS restores the terminal attributes when +initially opening a TTY. +This is the default on +.Fx , +but is present for +POSIX +compatibility. +The initial call to +.Fn open +on a TTY will always restore default terminal attributes on +.Fx . +.Pp +.Dv O_DIRECTORY +may be used to ensure the resulting file descriptor refers to a +directory. +This flag can be used to prevent applications with elevated privileges +from opening files which are even unsafe to open with +.Dv O_RDONLY , +such as device nodes. +.Pp +.Dv O_CLOEXEC +may be used to set +.Dv FD_CLOEXEC +flag for the newly returned file descriptor. +.Pp +.Dv O_CLOFORK +may be used to set +.Dv FD_CLOFORK +flag for the newly returned file descriptor. +The file will be closed on any child process created with +.Fn fork 2 , +.Fn vfork 2 +or +.Fn rfork 2 +with the +.Dv RFFDG +flag, remaining open in the parent. +Both the +.Dv O_CLOEXEC +and +.Dv O_CLOFORK +flags can be modified with the +.Dv F_SETFD +.Fn fcntl 2 +command. +.Pp +.Dv O_VERIFY +may be used to indicate to the kernel that the contents of the file should +be verified before allowing the open to proceed. +The details of what +.Dq verified +means is implementation specific. +The run-time linker (rtld) uses this flag to ensure shared objects have +been verified before operating on them. +.Pp +.Dv O_RESOLVE_BENEATH +returns +.Er ENOTCAPABLE +if any intermediate component of the specified relative path does not +reside in the directory hierarchy beneath the starting directory. +Absolute paths or even the temporal escape from beneath of the starting +directory is not allowed. +.Pp +When a directory +is opened with +.Dv O_SEARCH , +execute permissions are checked at open time. +The returned file descriptor +may not be used for any read operations like +.Xr getdirentries 2 . +The primary use of this descriptor is as the lookup descriptor for the +.Fn *at +family of functions. +If +.Dv O_SEARCH +was not requested at open time, then the +.Fn *at +functions use the current directory permissions for the directory referenced +by the descriptor at the time of the +.Fn *at +call. +.Pp +.Dv O_PATH +returns a file descriptor that can be used as a directory file descriptor for +.Fn openat +and other system calls taking a file descriptor argument, like +.Xr fstatat 2 +and others. +The other functionality of the returned file descriptor is limited to +the following descriptor-level operations: +.Pp +.Bl -tag -width __acl_aclcheck_fd -offset indent -compact +.It Xr fcntl 2 +but advisory locking is not allowed +.It Xr dup 2 +.It Xr close 2 +.It Xr fstat 2 +.It Xr fstatfs 2 +.It Xr fchdir 2 +.It Xr fchroot 2 +.It Xr fexecve 2 +.It Xr funlinkat 2 +can be passed as the third argument +.It Dv SCM_RIGHTS +can be passed over a +.Xr unix 4 +socket using a +.Dv SCM_RIGHTS +message +.It Xr kqueue 2 +only with +.Dv EVFILT_VNODE +.It Xr __acl_get_fd 2 +.It Xr __acl_aclcheck_fd 2 +.It Xr extattr 2 +.It Xr capsicum 4 +can be passed to +.Fn cap_*_limit +and +.Fn cap_*_get +system calls (such as +.Xr cap_rights_limit 2 ) . +.El +.Pp +Other operations like +.Xr read 2 , +.Xr ftruncate 2 , +and any other that operate on file and not on file descriptor (except +.Xr fstat 2 ) , +are not allowed. +.Pp +A file descriptor created with the +.Dv O_PATH +flag can be opened as a normal (operable) file descriptor by +specifying it as the +.Fa fd +argument to +.Fn openat +with an empty +.Fa path +and the +.Dv O_EMPTY_PATH +flag. +Such an open behaves as if the current path of the file referenced by +.Fa fd +is passed, except that path walk permissions are not checked. +See also the description of +.Dv AT_EMPTY_PATH +flag for +.Xr fstatat 2 +and related syscalls. +.Pp +Conversely, a file descriptor +.Dv fd +referencing a filesystem file can be converted to the +.Dv O_PATH +type of descriptor by using the following call +.Dl opath_fd = openat(fd, \[dq]\[dq], O_EMPTY_PATH | O_PATH); +.Pp +If successful, +.Fn open +returns a non-negative integer, termed a file descriptor. +It returns \-1 on failure. +The file descriptor value returned is the lowest numbered descriptor +currently not in use by the process. +The file pointer used to mark the current position within the +file is set to the beginning of the file. +.Pp +If a sleeping open of a device node from +.Xr devfs 4 +is interrupted by a signal, the call always fails with +.Er EINTR , +even if the +.Dv SA_RESTART +flag is set for the signal. +A sleeping open of a fifo (see +.Xr mkfifo 2 ) +is restarted as normal. +.Pp +When a new file is created, it is assigned the group of the directory +which contains it. +.Pp +Unless +.Dv O_CLOEXEC +flag was specified, +the new descriptor is set to remain open across +.Xr execve 2 +system calls; see +.Xr close 2 , +.Xr fcntl 2 +and the description of the +.Dv O_CLOEXEC +flag. +.Pp +When the +.Dv O_NAMEDATTR +flag is specified for an +.Fn openat +where the +.Fa fd +argument is for a file object, +a named attribute for the file object +is opened and not the file object itself. +If the +.Dv O_CREAT +flag has been specified as well, the named attribute will be +created if it does not exist. +When the +.Dv O_NAMEDATTR +flag is specified for a +.Fn open , +a named attribute for the current working directory is opened and +not the current working directory. +The +.Fa path +argument for this +.Fn openat +or +.Fn open +must be a single component name with no embedded +.Ql / . +If the +.Fa path +argument is +.Ql .\& +then the named attribute directory for the file object is opened. +(See +.Xr named_attribute 7 +for more information.) +.Pp +The system imposes a limit on the number of file descriptors +open simultaneously by one process. +The +.Xr getdtablesize 2 +system call returns the current system limit. +.Sh RETURN VALUES +If successful, +.Fn open +and +.Fn openat +return a non-negative integer, termed a file descriptor. +They return \-1 on failure, and set +.Va errno +to indicate the error. +.Sh ERRORS +The named file is opened unless: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +.Dv O_CREAT +is not set and the named file does not exist. +.It Bq Er ENOENT +A component of the path name that must exist does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er EACCES +The required permissions (for reading and/or writing) +are denied for the given flags. +.It Bq Er EACCES +.Dv O_TRUNC +is specified and write permission is denied. +.It Bq Er EACCES +.Dv O_CREAT +is specified, +the file does not exist, +and the directory in which it is to be created +does not permit writing. +.It Bq Er EPERM +.Dv O_CREAT +is specified, the file does not exist, and the directory in which it is to be +created has its immutable flag set, see the +.Xr chflags 2 +manual page for more information. +.It Bq Er EPERM +The named file has its immutable flag set and the file is to be modified. +.It Bq Er EPERM +The named file has its append-only flag set, the file is to be modified, and +.Dv O_TRUNC +is specified or +.Dv O_APPEND +is not specified. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EISDIR +The named file is a directory, and the arguments specify +it is to be modified. +.It Bq Er EISDIR +The named file is a directory, and the flags specified +.Dv O_CREAT +without +.Dv O_DIRECTORY . +.It Bq Er EROFS +The named file resides on a read-only file system, +and the file is to be modified. +.It Bq Er EROFS +.Dv O_CREAT +is specified and the named file would reside on a read-only file system. +.It Bq Er EMFILE +The process has already reached its limit for open file descriptors. +.It Bq Er ENFILE +The system file table is full. +.It Bq Er EMLINK +.Dv O_NOFOLLOW +was specified and the target is a symbolic link. +POSIX +specifies a different error for this case; see the note in +.Sx STANDARDS +below. +.It Bq Er ENXIO +The named file is a character special or block +special file, and the device associated with this special file +does not exist. +.It Bq Er ENXIO +.Dv O_NONBLOCK +is set, the named file is a fifo, +.Dv O_WRONLY +is set, and no process has the file open for reading. +.It Bq Er EINTR +The +.Fn open +operation was interrupted by a signal. +.It Bq Er EOPNOTSUPP +.Dv O_SHLOCK +or +.Dv O_EXLOCK +is specified but the underlying file system does not support locking. +.It Bq Er EOPNOTSUPP +The named file is a special file mounted through a file system that +does not support access to it (for example, NFS). +.It Bq Er EWOULDBLOCK +.Dv O_NONBLOCK +and one of +.Dv O_SHLOCK +or +.Dv O_EXLOCK +is specified and the file is locked. +.It Bq Er ENOSPC +.Dv O_CREAT +is specified, +the file does not exist, +and the directory in which the entry for the new file is being placed +cannot be extended because there is no space left on the file +system containing the directory. +.It Bq Er ENOSPC +.Dv O_CREAT +is specified, +the file does not exist, +and there are no free inodes on the file system on which the +file is being created. +.It Bq Er EDQUOT +.Dv O_CREAT +is specified, +the file does not exist, +and the directory in which the entry for the new file +is being placed cannot be extended because the +user's quota of disk blocks on the file system +containing the directory has been exhausted. +.It Bq Er EDQUOT +.Dv O_CREAT +is specified, +the file does not exist, +and the user's quota of inodes on the file system on +which the file is being created has been exhausted. +.It Bq Er EIO +An I/O error occurred while making the directory entry or +allocating the inode for +.Dv O_CREAT . +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.It Bq Er ETXTBSY +The file is a pure procedure (shared text) file that is being +executed and the +.Fn open +system call requests write access. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.It Bq Er EEXIST +.Dv O_CREAT +and +.Dv O_EXCL +were specified and the file exists. +.It Bq Er EOPNOTSUPP +An attempt was made to open a socket (not currently implemented). +.It Bq Er EINVAL +An attempt was made to open a descriptor with an illegal combination +of +.Dv O_RDONLY , +.Dv O_WRONLY , +or +.Dv O_RDWR , +and +.Dv O_EXEC +or +.Dv O_SEARCH . +.It Bq Er EINVAL +.Dv O_CREAT +is specified, +and the last component of the +.Fa path +argument is invalid on the file system on which the file is being created. +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is +neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.It Bq Er ENOTDIR +.Dv O_DIRECTORY +is specified and the file is not a directory. +.It Bq Er ECAPMODE +.Dv AT_FDCWD +is specified and the process is in capability mode. +.It Bq Er ECAPMODE +.Fn open +was called and the process is in capability mode. +.It Bq Er ENOTCAPABLE +.Fa path +is an absolute path and the process is in capability mode. +.It Bq Er ENOTCAPABLE +.Fa path +is an absolute path and +.Dv O_RESOLVE_BENEATH +is specified. +.It Bq Er ENOTCAPABLE +.Fa path +contains a ".." component leading to a directory outside +of the directory hierarchy specified by +.Fa fd +and the process is in capability mode. +.It Bq Er ENOTCAPABLE +.Fa path +contains a ".." component leading to a directory outside +of the directory hierarchy specified by +.Fa fd +and +.Dv O_RESOLVE_BENEATH +is specified. +.It Bq Er ENOTCAPABLE +.Fa path +contains a ".." component, the +.Dv vfs.lookup_cap_dotdot +.Xr sysctl 3 +is set, and the process is in capability mode. +.It Bq Er ENOATTR +.Dv O_NAMEDATTR +has been specified and the file object is not a named attribute +directory or named attribute. +.El +.Sh SEE ALSO +.Xr chmod 2 , +.Xr close 2 , +.Xr dup 2 , +.Xr fexecve 2 , +.Xr fhopen 2 , +.Xr getdtablesize 2 , +.Xr getfh 2 , +.Xr lgetfh 2 , +.Xr lseek 2 , +.Xr read 2 , +.Xr umask 2 , +.Xr write 2 , +.Xr fopen 3 , +.Xr capsicum 4 , +.Xr named_attribute 7 +.Sh STANDARDS +These functions are specified by +.St -p1003.1-2008 . +.Pp +.Fx +sets +.Va errno +to +.Er EMLINK instead of +.Er ELOOP +as specified by +POSIX +when +.Dv O_NOFOLLOW +is set in flags and the final component of pathname is a symbolic link +to distinguish it from the case of too many symbolic link traversals +in one of its non-final components. +.Pp +The Open Group Extended API Set 2 specification, that introduced the +.Fn *at +API, required that the test for whether +.Fa fd +is searchable is based on whether +.Fa fd +is open for searching, not whether the underlying directory currently +permits searches. +The present implementation of the +.Fa openat +system call is believed to be compatible with +.\" .St -p1003.1-2017 , +.\" XXX: This should be replaced in the future when an appropriate argument to +.\" the St macro is available: -p1003.1-2017 +.No IEEE Std 1003.1-2008, 2017 Edition ("POSIX.1") , +which specifies that behavior for +.Dv O_SEARCH , +in the absence of the flag the implementation checks the current +permissions of a directory. +.Sh HISTORY +The +.Fn open +function appeared in +.At v1 . +The +.Fn openat +function was introduced in +.Fx 8.0 . +.Dv O_DSYNC +appeared in 13.0. +.Dv O_NAMEDATTR +appeared in 15.0. +.Dv O_CLOFORK +appeared in +.Fx 15.0 . +.Sh BUGS +The +.Fa mode +argument is variadic and may result in different calling conventions +than might otherwise be expected. diff --git a/lib/libsys/pathconf.2 b/lib/libsys/pathconf.2 new file mode 100644 index 000000000000..79ac8310000d --- /dev/null +++ b/lib/libsys/pathconf.2 @@ -0,0 +1,279 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd July 5, 2025 +.Dt PATHCONF 2 +.Os +.Sh NAME +.Nm pathconf , +.Nm lpathconf , +.Nm fpathconf +.Nd get configurable pathname variables +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft long +.Fn pathconf "const char *path" "int name" +.Ft long +.Fn lpathconf "const char *path" "int name" +.Ft long +.Fn fpathconf "int fd" "int name" +.Sh DESCRIPTION +The +.Fn pathconf , +.Fn lpathconf +and +.Fn fpathconf +system calls provide a method for applications to determine the current +value of a configurable system limit or option variable associated +with a pathname or file descriptor. +.Pp +For +.Fn pathconf +and +.Fn lpathconf , +the +.Fa path +argument is the name of a file or directory. +For +.Fn fpathconf , +the +.Fa fd +argument is an open file descriptor. +The +.Fa name +argument specifies the system variable to be queried. +Symbolic constants for each name value are found in the include file +.Li <unistd.h> . +.Pp +The +.Fn lpathconf +system call is like +.Fn pathconf +except in the case where the named file is a symbolic link, +in which case +.Fn lpathconf +returns information about the link, +while +.Fn pathconf +returns information about the file the link references. +.Pp +The available values are as follows: +.Bl -tag -width 6n +.It Li _PC_LINK_MAX +The maximum file link count. +.It Li _PC_MAX_CANON +The maximum number of bytes in terminal canonical input line. +.It Li _PC_MAX_INPUT +The minimum maximum number of bytes for which space is available in +a terminal input queue. +.It Li _PC_NAME_MAX +The maximum number of bytes in a file name. +.It Li _PC_PATH_MAX +The maximum number of bytes in a pathname. +.It Li _PC_PIPE_BUF +The maximum number of bytes which will be written atomically to a pipe. +.It Li _PC_CHOWN_RESTRICTED +Return 1 if appropriate privilege is required for the +.Xr chown 2 +system call, otherwise 0. +.St -p1003.1-2001 +requires appropriate privilege in all cases, but this behavior was optional +in prior editions of the standard. +.It Li _PC_NO_TRUNC +Return greater than zero if attempts to use pathname components longer than +.Brq Dv NAME_MAX +will result in an +.Bq Er ENAMETOOLONG +error; otherwise, such components will be truncated to +.Brq Dv NAME_MAX . +.St -p1003.1-2001 +requires the error in all cases, but this behavior was optional in prior +editions of the standard, and some +.No non- Ns Tn POSIX Ns -compliant +file systems do not support this behavior. +.It Li _PC_VDISABLE +Returns the terminal character disabling value. +.It Li _PC_ASYNC_IO +Return 1 if asynchronous I/O is supported, otherwise 0. +.It Li _PC_PRIO_IO +Returns 1 if prioritised I/O is supported for this file, +otherwise 0. +.It Li _PC_SYNC_IO +Returns 1 if synchronised I/O is supported for this file, otherwise 0. +.It Li _PC_ALLOC_SIZE_MIN +Minimum number of bytes of storage allocated for any portion of a file. +.It Li _PC_FILESIZEBITS +Number of bits needed to represent the maximum file size. +.It Li _PC_REC_INCR_XFER_SIZE +Recommended increment for file transfer sizes between +.Dv _PC_REC_MIN_XFER_SIZE +and +.Dv _PC_REC_MAX_XFER_SIZE . +.It Li _PC_REC_MAX_XFER_SIZE +Maximum recommended file transfer size. +.It Li _PC_REC_MIN_XFER_SIZE +Minimum recommended file transfer size. +.It Li _PC_REC_XFER_ALIGN +Recommended file transfer buffer alignment. +.It Li _PC_SYMLINK_MAX +Maximum number of bytes in a symbolic link. +.It Li _PC_ACL_EXTENDED +Returns 1 if an Access Control List (ACL) can be set on the specified +file, otherwise 0. +.It Li _PC_ACL_NFS4 +Returns 1 if an NFSv4 ACLs can be set on the specified +file, otherwise 0. +.It Li _PC_ACL_PATH_MAX +Maximum number of ACL entries per file. +.It Li _PC_CAP_PRESENT +Returns 1 if a capability state can be set on the specified file, +otherwise 0. +.It Li _PC_INF_PRESENT +Returns 1 if an information label can be set on the specified file, +otherwise 0. +.It Li _PC_MAC_PRESENT +Returns 1 if a Mandatory Access Control (MAC) label can be set on the +specified file, otherwise 0. +.It Li _PC_MIN_HOLE_SIZE +If a file system supports the reporting of holes (see +.Xr lseek 2 ) , +.Fn pathconf +and +.Fn fpathconf +return a positive number that represents the minimum hole size returned in +bytes. +The offsets of holes returned will be aligned to this same value. +A special value of 1 is returned if the file system does not specify the minimum +hole size but still reports holes. +.It Li _PC_DEALLOC_PRESENT +Return 1 if a file system supports hole-punching (see +.Xr fspacectl 2 ) , +otherwise 0. +.It Li _PC_NAMEDATTR_ENABLED +Return 1 if named attributes are enabled for the file system, otherwise 0. +.It Li _PC_HAS_NAMEDATTR +Return 1 if one or more named attributes exist for the file, otherwise 0. +.It Li _PC_HAS_HIDDENSYSTEM +Return 1 if both +.Dv UF_HIDDEN +and +.Dv UF_SYSTEM +flags can be set by +.Xr chflags 2 , +otherwise 0. +.El +.Sh RETURN VALUES +If the call to +.Fn pathconf +or +.Fn fpathconf +is not successful, \-1 is returned and +.Va errno +is set appropriately. +Otherwise, if the variable is associated with functionality that does +not have a limit in the system, \-1 is returned and +.Va errno +is not modified. +Otherwise, the current variable value is returned. +.Sh ERRORS +If any of the following conditions occur, the +.Fn pathconf +and +.Fn fpathconf +system calls shall return -1 and set +.Va errno +to the corresponding value. +.Bl -tag -width Er +.It Bq Er EINVAL +The value of the +.Fa name +argument is invalid. +.It Bq Er EINVAL +The implementation does not support an association of the variable +name with the associated file. +.El +.Pp +The +.Fn pathconf +system call +will fail if: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded +.Brq Dv NAME_MAX +characters (but see +.Dv _PC_NO_TRUNC +above), +or an entire path name exceeded +.Brq Dv PATH_MAX +characters. +.It Bq Er ENOENT +The named file does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.El +.Pp +The +.Fn fpathconf +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument +is not a valid open file descriptor. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.El +.Sh SEE ALSO +.Xr chflags 2 , +.Xr lseek 2 , +.Xr sysctl 3 +.Sh HISTORY +The +.Fn pathconf +and +.Fn fpathconf +system calls first appeared in +.Bx 4.4 . +The +.Fn lpathconf +system call first appeared in +.Fx 8.0 . diff --git a/lib/libsys/pdfork.2 b/lib/libsys/pdfork.2 new file mode 100644 index 000000000000..c5319177f90f --- /dev/null +++ b/lib/libsys/pdfork.2 @@ -0,0 +1,186 @@ +.\" +.\" Copyright (c) 2009-2010, 2012-2013 Robert N. M. Watson +.\" All rights reserved. +.\" +.\" This software was developed at the University of Cambridge Computer +.\" Laboratory with support from a grant from Google, Inc. +.\" +.\" This software was developed by SRI International and the University of +.\" Cambridge Computer Laboratory under DARPA/AFRL contract (FA8750-10-C-0237) +.\" ("CTSRD"), as part of the DARPA CRASH research programme. +.\" +.\" 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. +.\" +.Dd October 14, 2018 +.Dt PDFORK 2 +.Os +.Sh NAME +.Nm pdfork , +.Nm pdgetpid , +.Nm pdkill +.Nd System calls to manage process descriptors +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/procdesc.h +.Ft pid_t +.Fn pdfork "int *fdp" "int flags" +.Ft int +.Fn pdgetpid "int fd" "pid_t *pidp" +.Ft int +.Fn pdkill "int fd" "int signum" +.Sh DESCRIPTION +Process descriptors are special file descriptors that represent processes, +and are created using +.Fn pdfork , +a variant of +.Xr fork 2 , +which, if successful, returns a process descriptor in the integer pointed to +by +.Fa fdp . +Processes created via +.Fn pdfork +will not cause +.Dv SIGCHLD +on termination. +.Fn pdfork +can accept the flags: +.Bl -tag -width ".Dv PD_DAEMON" +.It Dv PD_DAEMON +Instead of the default terminate-on-close behaviour, allow the process to +live until it is explicitly killed with +.Xr kill 2 . +.Pp +This option is not permitted in +.Xr capsicum 4 +capability mode (see +.Xr cap_enter 2 ) . +.El +.Bl -tag -width ".Dv PD_DAEMON" +.It Dv PD_CLOEXEC +Set close-on-exec on process descriptor. +.El +.Pp +.Fn pdgetpid +queries the process ID (PID) in the process descriptor +.Fa fd . +.Pp +.Fn pdkill +is functionally identical to +.Xr kill 2 , +except that it accepts a process descriptor, +.Fa fd , +rather than a PID. +.Pp +The following system calls also have effects specific to process descriptors: +.Pp +.Xr fstat 2 +queries status of a process descriptor; currently only the +.Fa st_mode , +.Fa st_birthtime , +.Fa st_atime , +.Fa st_ctime +and +.Fa st_mtime +fields are defined. +If the owner read, write, and execute bits are set then the +process represented by the process descriptor is still alive. +.Pp +.Xr poll 2 +and +.Xr select 2 +allow waiting for process state transitions; currently only +.Dv POLLHUP +is defined, and will be raised when the process dies. +Process state transitions can also be monitored using +.Xr kqueue 2 +filter +.Dv EVFILT_PROCDESC ; +currently only +.Dv NOTE_EXIT +is implemented. +.Pp +.Xr close 2 +will close the process descriptor unless +.Dv PD_DAEMON +is set; if the process is still alive and this is +the last reference to the process descriptor, the process will be terminated +with the signal +.Dv SIGKILL . +.Sh RETURN VALUES +.Fn pdfork +returns a PID, 0 or -1, as +.Xr fork 2 +does. +.Pp +.Fn pdgetpid +and +.Fn pdkill +return 0 on success and -1 on failure. +.Sh ERRORS +These functions may return the same error numbers as their PID-based equivalents +(e.g. +.Fn pdfork +may return the same error numbers as +.Xr fork 2 ) , +with the following additions: +.Bl -tag -width Er +.It Bq Er EINVAL +The signal number given to +.Fn pdkill +is invalid. +.It Bq Er ENOTCAPABLE +The process descriptor being operated on has insufficient rights (e.g. +.Dv CAP_PDKILL +for +.Fn pdkill ) . +.El +.Sh SEE ALSO +.Xr close 2 , +.Xr fork 2 , +.Xr fstat 2 , +.Xr kill 2 , +.Xr kqueue 2 , +.Xr poll 2 , +.Xr wait4 2 , +.Xr capsicum 4 , +.Xr procdesc 4 +.Sh HISTORY +The +.Fn pdfork , +.Fn pdgetpid , +and +.Fn pdkill +system calls first appeared in +.Fx 9.0 . +.Pp +Support for process descriptors mode was developed as part of the +.Tn TrustedBSD +Project. +.Sh AUTHORS +.An -nosplit +These functions and the capability facility were created by +.An Robert N. M. Watson Aq Mt rwatson@FreeBSD.org +and +.An Jonathan Anderson Aq Mt jonathan@FreeBSD.org +at the University of Cambridge Computer Laboratory with support from a grant +from Google, Inc. diff --git a/lib/libsys/pipe.2 b/lib/libsys/pipe.2 new file mode 100644 index 000000000000..37d6eba420de --- /dev/null +++ b/lib/libsys/pipe.2 @@ -0,0 +1,182 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd May 17, 2025 +.Dt PIPE 2 +.Os +.Sh NAME +.Nm pipe , +.Nm pipe2 +.Nd create descriptor pair for interprocess communication +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn pipe "int fildes[2]" +.Ft int +.Fn pipe2 "int fildes[2]" "int flags" +.Sh DESCRIPTION +The +.Fn pipe +function +creates a +.Em pipe , +which is an object allowing +bidirectional data flow, +and allocates a pair of file descriptors. +.Pp +The +.Fn pipe2 +system call allows control over the attributes of the file descriptors +via the +.Fa flags +argument. +Values for +.Fa flags +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.In fcntl.h : +.Bl -tag -width ".Dv O_NONBLOCK" +.It Dv O_CLOEXEC +Set the close-on-exec flag for the new file descriptors. +.It Dv O_CLOFORK +Set the close-on-fork flag for the new file descriptors. +.It Dv O_NONBLOCK +Set the non-blocking flag for the ends of the pipe. +.El +.Pp +If the +.Fa flags +argument is 0, the behavior is identical to a call to +.Fn pipe . +.Pp +By convention, the first descriptor is normally used as the +.Em read end +of the pipe, +and the second is normally the +.Em write end , +so that data written to +.Fa fildes[1] +appears on (i.e., can be read from) +.Fa fildes[0] . +This allows the output of one program to be +sent +to another program: +the source's standard output is set up to be +the write end of the pipe, +and the sink's standard input is set up to be +the read end of the pipe. +The pipe itself persists until all its associated descriptors are +closed. +.Pp +A pipe that has had an end closed is considered +.Em widowed . +Writing on such a pipe causes the writing process to receive +a +.Dv SIGPIPE +signal. +Widowing a pipe is the only way to deliver end-of-file to a reader: +after the reader consumes any buffered data, reading a widowed pipe +returns a zero count. +.Pp +The bidirectional nature of this implementation of pipes is not +portable to older systems, so it is recommended to use the convention +for using the endpoints in the traditional manner when using a +pipe in one direction. +.Sh IMPLEMENTATION NOTES +The +.Fn pipe +function calls the +.Fn pipe2 +system call. +As a result, system call traces such as those captured by +.Xr dtrace 1 +or +.Xr ktrace 1 +will show calls to +.Fn pipe2 . +.Sh RETURN VALUES +.Rv -std pipe +.Sh ERRORS +The +.Fn pipe +and +.Fn pipe2 +system calls will fail if: +.Bl -tag -width Er +.It Bq Er EFAULT +.Ar fildes +argument points to an invalid memory location. +.It Bq Er EMFILE +Too many descriptors are active. +.It Bq Er ENFILE +The system file table is full. +.It Bq Er ENOMEM +Not enough kernel memory to establish a pipe. +.El +.Pp +The +.Fn pipe2 +system call will also fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa flags +argument is invalid. +.El +.Sh SEE ALSO +.Xr sh 1 , +.Xr fork 2 , +.Xr read 2 , +.Xr socketpair 2 , +.Xr write 2 +.Sh HISTORY +The +.Fn pipe +function appeared in +.At v3 . +.Pp +Bidirectional pipes were first used on +.At V.4 . +.Pp +The +.Fn pipe2 +function appeared in +.Fx 10.0 . +.Pp +The +.Fn pipe +function became a wrapper around +.Fn pipe2 +in +.Fx 11.0 . +.Pp +The +.Dv O_CLOFORK +flag appeared in +.Fx 15.0 . diff --git a/lib/libsys/poll.2 b/lib/libsys/poll.2 new file mode 100644 index 000000000000..6e6ed33f7a6b --- /dev/null +++ b/lib/libsys/poll.2 @@ -0,0 +1,294 @@ +.\" $NetBSD: poll.2,v 1.3 1996/09/07 21:53:08 mycroft Exp $ +.\" +.\" Copyright (c) 1996 Charles M. Hannum. All rights reserved. +.\" +.\" 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. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by Charles M. Hannum. +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 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. +.\" +.Dd December 11, 2024 +.Dt POLL 2 +.Os +.Sh NAME +.Nm poll +.Nd synchronous I/O multiplexing +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In poll.h +.Ft int +.Fn poll "struct pollfd fds[]" "nfds_t nfds" "int timeout" +.Ft int +.Fo ppoll +.Fa "struct pollfd fds[]" +.Fa "nfds_t nfds" +.Fa "const struct timespec * restrict timeout" +.Fa "const sigset_t * restrict newsigmask" +.Fc +.Sh DESCRIPTION +The +.Fn poll +system call +examines a set of file descriptors to see if some of them are ready for +I/O. +The +.Fa fds +argument is a pointer to an array of pollfd structures as defined in +.In poll.h +(shown below). +The +.Fa nfds +argument determines the size of the +.Fa fds +array. +.Bd -literal +struct pollfd { + int fd; /* file descriptor */ + short events; /* events to look for */ + short revents; /* events returned */ +}; +.Ed +.Pp +The fields of +.Fa struct pollfd +are as follows: +.Bl -tag -width XXXrevents +.It fd +File descriptor to poll. +If fd is equal to -1 then +.Fa revents +is cleared (set to zero), and that pollfd is not checked. +.It events +Events to poll for. +(See below.) +.It revents +Events which may occur. +(See below.) +.El +.Pp +The event bitmasks in +.Fa events +and +.Fa revents +have the following bits: +.Bl -tag -width XXXPOLLWRNORM +.It POLLIN +Data other than high priority data may be read without blocking. +.It POLLRDNORM +Normal data may be read without blocking. +.It POLLRDBAND +Data with a non-zero priority may be read without blocking. +.It POLLPRI +High priority data may be read without blocking. +.It POLLOUT +.It POLLWRNORM +Normal data may be written without blocking. +.It POLLWRBAND +Data with a non-zero priority may be written without blocking. +.It POLLERR +An exceptional condition has occurred on the device or socket. +This +flag is always checked, even if not present in the +.Fa events +bitmask. +.It POLLHUP +The device or socket has been disconnected. +This flag is always +checked, even if not present in the +.Fa events +bitmask. +Note that +POLLHUP +and +POLLOUT +should never be present in the +.Fa revents +bitmask at the same time. +.It POLLRDHUP +Remote peer closed connection, or shut down writing. +Unlike +POLLHUP, +POLLRDHUP +must be present in the +.Fa events +bitmask to be reported. +Applies only to stream sockets. +.It POLLNVAL +The file descriptor is not open, +or in capability mode the file descriptor has insufficient rights. +This flag is always checked, even +if not present in the +.Fa events +bitmask. +.El +.Pp +If +.Fa timeout +is neither zero nor INFTIM (-1), it specifies a maximum interval to +wait for any file descriptor to become ready, in milliseconds. +If +.Fa timeout +is INFTIM (-1), the poll blocks indefinitely. +If +.Fa timeout +is zero, then +.Fn poll +will return without blocking. +.Pp +The +.Fn ppoll +system call, unlike +.Fn poll , +is used to safely wait until either a set of file descriptors becomes +ready or until a signal is caught. +The +.Fa fds +and +.Fa nfds +arguments are identical to the analogous arguments of +.Fn poll . +The +.Fa timeout +argument in +.Fn ppoll +points to a +.Vt "const struct timespec" +which is defined in +.In sys/timespec.h +(shown below) rather than the +.Vt "int timeout" +used by +.Fn poll . +A null pointer may be passed to indicate that +.Fn ppoll +should wait indefinitely. +Finally, +.Fa newsigmask +specifies a signal mask which is set while waiting for input. +When +.Fn ppoll +returns, the original signal mask is restored. +.Bd -literal +struct timespec { + time_t tv_sec; /* seconds */ + long tv_nsec; /* and nanoseconds */ +}; +.Ed +.Sh RETURN VALUES +The +.Fn poll +system call +returns the number of descriptors that are ready for I/O, or -1 if an +error occurred. +If the time limit expires, +.Fn poll +returns 0. +If +.Fn poll +returns with an error, +including one due to an interrupted system call, +the +.Fa fds +array will be unmodified. +.Sh COMPATIBILITY +This implementation differs from the historical one in that a given +file descriptor may not cause +.Fn poll +to return with an error. +In cases where this would have happened in +the historical implementation (e.g.\& trying to poll a +.Xr revoke 2 Ns ed +descriptor), this implementation instead copies the +.Fa events +bitmask to the +.Fa revents +bitmask. +Attempting to perform I/O on this descriptor will then +return an error. +This behaviour is believed to be more useful. +.Sh ERRORS +An error return from +.Fn poll +indicates: +.Bl -tag -width Er +.It Bq Er EFAULT +The +.Fa fds +argument +points outside the process's allocated address space. +.It Bq Er EINTR +A signal was delivered before the time limit expired and +before any of the selected events occurred. +.It Bq Er EINVAL +The specified time limit is invalid. +One of its components is negative or too large. +.It Bq Er EINVAL +The number of pollfd structures specified by +.Fa nfds +exceeds the system tunable +.Va kern.maxfilesperproc +and +.Dv FD_SETSIZE . +.El +.Sh SEE ALSO +.Xr accept 2 , +.Xr connect 2 , +.Xr kqueue 2 , +.Xr pselect 2 , +.Xr read 2 , +.Xr recv 2 , +.Xr select 2 , +.Xr send 2 , +.Xr write 2 +.Sh STANDARDS +The +.Fn poll +function conforms to +.St -p1003.1-2001 . +The +.Fn ppoll +function conforms to +.St -p1003.1-2024 . +The +POLLRDHUP +flag is not specified by POSIX, but is compatible with Linux and illumos. +.Sh HISTORY +The +.Fn poll +function appeared in +.At V . +This manual page and the core of the implementation was taken from +.Nx . +The +.Fn ppoll +function first appeared in +.Fx 10.2 +.Sh BUGS +The distinction between some of the fields in the +.Fa events +and +.Fa revents +bitmasks is really not useful without STREAMS. +The fields are +defined for compatibility with existing software. diff --git a/lib/libsys/posix_fadvise.2 b/lib/libsys/posix_fadvise.2 new file mode 100644 index 000000000000..24cc3601e268 --- /dev/null +++ b/lib/libsys/posix_fadvise.2 @@ -0,0 +1,140 @@ +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd March 30, 2020 +.Dt POSIX_FADVISE 2 +.Os +.Sh NAME +.Nm posix_fadvise +.Nd give advice about use of file data +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In fcntl.h +.Ft int +.Fn posix_fadvise "int fd" "off_t offset" "off_t len" "int advice" +.Sh DESCRIPTION +The +.Fn posix_fadvise +system call +allows a process to describe to the system its data access behavior for an +open file descriptor +.Fa fd . +The advice covers the data starting at offset +.Fa offset +and continuing for +.Fa len +bytes. +If +.Fa len +is zero, +all data from +.Fa offset +to the end of the file is covered. +.Pp +The behavior is specified by the +.Fa advice +parameter and may be one of: +.Bl -tag -width POSIX_FADV_SEQUENTIAL +.It Dv POSIX_FADV_NORMAL +Tells the system to revert to the default data access behavior. +.It Dv POSIX_FADV_RANDOM +Is a hint that file data will be accessed randomly, +and prefetching is likely not advantageous. +.It Dv POSIX_FADV_SEQUENTIAL +Tells the system that file data will be accessed sequentially. +This currently does nothing as the default behavior uses heuristics to +detect sequential behavior. +.It Dv POSIX_FADV_WILLNEED +Tells the system that the specified data will be accessed in the near future. +The system may initiate an asynchronous read of the data if it is not already +present in memory. +.It Dv POSIX_FADV_DONTNEED +Tells the system that the specified data will not be accessed in the near +future. +The system may decrease the in-memory priority of clean data within the +specified range and future access to this data may require a read operation. +.It Dv POSIX_FADV_NOREUSE +Tells the system that the specified data will only be accessed once and +then not reused. +The system may decrease the in-memory priority of data once it has been +read or written. +Future access to this data may require a read operation. +.El +.Sh RETURN VALUES +If successful, +.Fn posix_fadvise +returns zero. +It returns an error on failure, without setting +.Va errno . +.Sh ERRORS +Possible failure conditions: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid file descriptor. +.It Bq Er EINVAL +The +.Fa advice +argument is not valid. +.It Bq Er EINVAL +The +.Fa offset +or +.Fa len +arguments are negative, +or +.Fa offset ++ +.Fa len +is greater than the maximum file size. +.It Bq Er ENODEV +The +.Fa fd +argument does not refer to a regular file. +.It Bq Er ESPIPE +The +.Fa fd +argument is associated with a pipe or FIFO. +.It Bq Er EIO +An I/O error occurred while reading from or writing to a file system. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.El +.Sh SEE ALSO +.Xr madvise 2 +.Sh STANDARDS +The +.Fn posix_fadvise +interface conforms to +.St -p1003.1-2001 . +.Sh HISTORY +The +.Fn posix_fadvise +system call first appeared in +.Fx 9.1 . diff --git a/lib/libsys/posix_fallocate.2 b/lib/libsys/posix_fallocate.2 new file mode 100644 index 000000000000..8be075b41331 --- /dev/null +++ b/lib/libsys/posix_fallocate.2 @@ -0,0 +1,149 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd March 30, 2020 +.Dt POSIX_FALLOCATE 2 +.Os +.Sh NAME +.Nm posix_fallocate +.Nd pre-allocate storage for a range in a file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In fcntl.h +.Ft int +.Fn posix_fallocate "int fd" "off_t offset" "off_t len" +.Sh DESCRIPTION +Required storage for the range +.Fa offset +to +.Fa offset + +.Fa len +in the file referenced by +.Fa fd +is guaranteed to be allocated upon successful return. +That is, if +.Fn posix_fallocate +returns successfully, subsequent writes to the specified file data +will not fail due to lack of free space on the file system storage +media. +Any existing file data in the specified range is unmodified. +If +.Fa offset + +.Fa len +is beyond the current file size, then +.Fn posix_fallocate +will adjust the file size to +.Fa offset + +.Fa len . +Otherwise, the file size will not be changed. +.Pp +Space allocated by +.Fn posix_fallocate +will be freed by a successful call to +.Xr creat 2 +or +.Xr open 2 +that truncates the size of the file. +Space allocated via +.Fn posix_fallocate +may be freed by a successful call to +.Xr ftruncate 2 +that reduces the file size to a size smaller than +.Fa offset + +.Fa len . +.Sh RETURN VALUES +If successful, +.Fn posix_fallocate +returns zero. +It returns an error on failure, without setting +.Va errno . +.Sh ERRORS +Possible failure conditions: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid file descriptor. +.It Bq Er EBADF +The +.Fa fd +argument references a file that was opened without write permission. +.It Bq Er EFBIG +The value of +.Fa offset + +.Fa len +is greater than the maximum file size. +.It Bq Er EINTR +A signal was caught during execution. +.It Bq Er EINVAL +The +.Fa len +argument was less than or equal to zero, the +.Fa offset +argument was less than zero, +or the operation is not supported by the file system. +.It Bq Er EIO +An I/O error occurred while reading from or writing to a file system. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.It Bq Er ENODEV +The +.Fa fd +argument does not refer to a file that supports +.Nm . +.It Bq Er ENOSPC +There is insufficient free space remaining on the file system storage +media. +.It Bq Er ENOTCAPABLE +The file descriptor +.Fa fd +has insufficient rights. +.It Bq Er ESPIPE +The +.Fa fd +argument is associated with a pipe or FIFO. +.El +.Sh SEE ALSO +.Xr creat 2 , +.Xr ftruncate 2 , +.Xr open 2 , +.Xr unlink 2 +.Sh STANDARDS +The +.Fn posix_fallocate +system call conforms to +.St -p1003.1-2004 . +.Sh HISTORY +The +.Fn posix_fallocate +function appeared in +.Fx 9.0 . +.Sh AUTHORS +.Fn posix_fallocate +and this manual page were initially written by +.An Matthew Fleming Aq Mt mdf@FreeBSD.org . diff --git a/lib/libsys/posix_openpt.2 b/lib/libsys/posix_openpt.2 new file mode 100644 index 000000000000..667dcbeba33d --- /dev/null +++ b/lib/libsys/posix_openpt.2 @@ -0,0 +1,138 @@ +.\" Copyright (c) 2008 Ed Schouten <ed@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Portions of this software were developed under sponsorship from Snow +.\" B.V., the Netherlands. +.\" +.\" 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. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.Dd September 21, 2016 +.Dt POSIX_OPENPT 2 +.Os +.Sh NAME +.Nm posix_openpt +.Nd "open a pseudo-terminal device" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In fcntl.h +.In stdlib.h +.Ft int +.Fn posix_openpt "int oflag" +.Sh DESCRIPTION +The +.Fn posix_openpt +function allocates a new pseudo-terminal and establishes a connection +with its master device. +A slave device shall be created in +.Pa /dev/pts . +After the pseudo-terminal has been allocated, the slave device should +have the proper permissions before it can be used (see +.Xr grantpt 3 ) . +The name of the slave device can be determined by calling +.Xr ptsname 3 . +.Pp +The file status flags and file access modes of the open file description +shall be set according to the value of +.Fa oflag . +Values for +.Fa oflag +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.In fcntl.h : +.Bl -tag -width ".Dv O_CLOEXEC" +.It Dv O_RDWR +Open for reading and writing. +.It Dv O_NOCTTY +If set +.Fn posix_openpt +shall not cause the terminal device to become the controlling terminal +for the process. +.It Dv O_CLOEXEC +Set the close-on-exec flag for the new file descriptor. +.El +.Pp +The +.Fn posix_openpt +function shall fail when +.Fa oflag +contains other values. +.Sh RETURN VALUES +Upon successful completion, the +.Fn posix_openpt +function shall allocate a new pseudo-terminal device and return a +non-negative integer representing a file descriptor, which is connected +to its master device. +Otherwise, -1 shall be returned and errno set to indicate the error. +.Sh ERRORS +The +.Fn posix_openpt +function shall fail if: +.Bl -tag -width Er +.It Bq Er ENFILE +The system file table is full. +.It Bq Er EINVAL +The value of +.Fa oflag +is not valid. +.It Bq Er EAGAIN +Out of pseudo-terminal resources. +.El +.Sh SEE ALSO +.Xr ptsname 3 , +.Xr pts 4 , +.Xr tty 4 +.Sh STANDARDS +The +.Fn posix_openpt +function conforms to +.St -p1003.1-2001 . +The ability to use +.Dv O_CLOEXEC +is an extension to the standard. +.Sh HISTORY +The +.Fn posix_openpt +function appeared in +.Fx 5.0 . +In +.Fx 8.0 , +this function was changed to a system call. +.Sh NOTES +The flag +.Dv O_NOCTTY +is included for compatibility; in +.Fx , +opening a terminal does not cause it to become a process's controlling +terminal. +.Sh AUTHORS +.An \&Ed Schouten Aq Mt ed@FreeBSD.org diff --git a/lib/libsys/powerpc/Makefile.sys b/lib/libsys/powerpc/Makefile.sys new file mode 100644 index 000000000000..9979d5179f51 --- /dev/null +++ b/lib/libsys/powerpc/Makefile.sys @@ -0,0 +1,4 @@ +SRCS+= __vdso_gettc.c \ + sched_getcpu_gen.c + +MDASM+= cerror.S diff --git a/lib/libsys/powerpc/Makefile.thr b/lib/libsys/powerpc/Makefile.thr new file mode 100644 index 000000000000..52e861709faf --- /dev/null +++ b/lib/libsys/powerpc/Makefile.thr @@ -0,0 +1 @@ +SRCS+= _umtx_op_err.S diff --git a/lib/libsys/powerpc/SYS.h b/lib/libsys/powerpc/SYS.h new file mode 100644 index 000000000000..04672ed51528 --- /dev/null +++ b/lib/libsys/powerpc/SYS.h @@ -0,0 +1,65 @@ +/*- + * SPDX-License-Identifier: BSD-3-Clause + * + * Copyright (c) 2002 Benno Rice. All rights reserved. + * Copyright (c) 2002 David E. O'Brien. All rights reserved. + * + * 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. + * 3. Neither the name of the author nor the names of any contributors + * may be used to endorse or promote products derived from this software + * without specific prior written permission. + * + * 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 REGENTS 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. + * + * $NetBSD: SYS.h,v 1.8 2002/01/14 00:55:56 thorpej Exp $ + */ + +#include <sys/syscall.h> +#include <machine/asm.h> + +#define _SYSCALL(name) \ + .text; \ + .align 2; \ + li 0,(SYS_##name); \ + sc + +#ifndef _SYSCALL_BODY +#define _SYSCALL_BODY(name) \ + _SYSCALL(name); \ + bnslr; \ + b CNAME(HIDENAME(cerror)) +#endif + +#define PSEUDO(name) \ + .text; \ + .align 2; \ +ENTRY(__sys_##name); \ + WEAK_REFERENCE(__sys_##name, _##name); \ + _SYSCALL_BODY(name); \ +END(__sys_##name) + +#define RSYSCALL(name) \ + .text; \ + .align 2; \ +ENTRY(__sys_##name); \ + WEAK_REFERENCE(__sys_##name, name); \ + WEAK_REFERENCE(__sys_##name, _##name); \ + _SYSCALL_BODY(name); \ +END(__sys_##name) diff --git a/lib/libsys/powerpc/__vdso_gettc.c b/lib/libsys/powerpc/__vdso_gettc.c new file mode 100644 index 000000000000..82b8e2f27384 --- /dev/null +++ b/lib/libsys/powerpc/__vdso_gettc.c @@ -0,0 +1,65 @@ +/*- + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (c) 2020 Brandon Bergren <bdragon@FreeBSD.org> + * + * This software was developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * 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. + */ + +#include <sys/types.h> +#include <sys/elf.h> +#include <sys/time.h> +#include <sys/vdso.h> + +#include <machine/cpufunc.h> +#include <machine/spr.h> + +#include <errno.h> + +#include "libc_private.h" + +#pragma weak __vdso_gettc +int +__vdso_gettc(const struct vdso_timehands *th, u_int *tc) +{ + + if (__predict_false(th->th_algo != VDSO_TH_ALGO_PPC_TB)) + return (ENOSYS); + /* + * While the timebase is a 64 bit quantity, we are only interested + * in the lower 32 bits of it. + */ + *tc = mfspr(TBR_TBL); + + return (0); +} + +#pragma weak __vdso_gettimekeep +int +__vdso_gettimekeep(struct vdso_timekeep **tk) +{ + + return (_elf_aux_info(AT_TIMEKEEP, tk, sizeof(*tk))); +} diff --git a/lib/libsys/powerpc/_umtx_op_err.S b/lib/libsys/powerpc/_umtx_op_err.S new file mode 100644 index 000000000000..a954962515f6 --- /dev/null +++ b/lib/libsys/powerpc/_umtx_op_err.S @@ -0,0 +1,39 @@ +/*- + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (c) 2019 Brandon Bergren <bdragon@FreeBSD.org> + * + * 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. + */ + +#include <machine/asm.h> +#include <sys/syscall.h> + + .text + .align 2 +ENTRY(_umtx_op_err) + li %r0, SYS__umtx_op + sc + blr +END(_umtx_op_err) + + .section .note.GNU-stack,"",%progbits diff --git a/lib/libsys/powerpc/cerror.S b/lib/libsys/powerpc/cerror.S new file mode 100644 index 000000000000..64204c5a1ddf --- /dev/null +++ b/lib/libsys/powerpc/cerror.S @@ -0,0 +1,66 @@ +/*- + * Copyright (c) 2002 Peter Grehan. + * All rights reserved. + * + * 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. + */ +/* $NetBSD: cerror.S,v 1.5 2000/01/27 14:58:48 kleink Exp $ */ + +#include <machine/asm.h> +#include "SYS.h" + + .globl HIDENAME(cerror) + .globl CNAME(__error) + + /* + * The __error() function is thread aware. For non-threaded + * programs and the initial thread in threaded programs, + * it returns a pointer to the global errno variable. + */ +HIDENAME(cerror): + mflr %r0 + stwu %r1,-20(%r1) /* allocate new stack frame */ + stw %r0,24(%r1) /* and save lr, r31 */ + stw %r31,12(%r1) +#ifdef __PIC__ + stw %r30,8(%r1) + bcl 20,31,1f +1: + mflr %r30 + addis %r30,%r30,_GLOBAL_OFFSET_TABLE_-1b@ha + addi %r30,%r30,_GLOBAL_OFFSET_TABLE_-1b@l +#endif + mr %r31,%r3 /* stash errval in callee-saved register */ + bl PIC_PLT(CNAME(__error)) + stw %r31,0(%r3) /* store errval into &errno */ + lwz %r0,24(%r1) + lwz %r31,12(%r1) +#ifdef __PIC__ + lwz %r30,8(%r1) +#endif + mtlr %r0 + la %r1,20(%r1) + li %r3,-1 + li %r4,-1 + blr /* return to callers caller */ + + .section .note.GNU-stack,"",%progbits diff --git a/lib/libsys/powerpc64/Makefile.sys b/lib/libsys/powerpc64/Makefile.sys new file mode 100644 index 000000000000..9979d5179f51 --- /dev/null +++ b/lib/libsys/powerpc64/Makefile.sys @@ -0,0 +1,4 @@ +SRCS+= __vdso_gettc.c \ + sched_getcpu_gen.c + +MDASM+= cerror.S diff --git a/lib/libsys/powerpc64/SYS.h b/lib/libsys/powerpc64/SYS.h new file mode 100644 index 000000000000..ceb85bb4e361 --- /dev/null +++ b/lib/libsys/powerpc64/SYS.h @@ -0,0 +1,73 @@ +/*- + * SPDX-License-Identifier: BSD-3-Clause + * + * Copyright (c) 2002 Benno Rice. All rights reserved. + * Copyright (c) 2002 David E. O'Brien. All rights reserved. + * + * 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. + * 3. Neither the name of the author nor the names of any contributors + * may be used to endorse or promote products derived from this software + * without specific prior written permission. + * + * 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 REGENTS 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. + * + * $NetBSD: SYS.h,v 1.8 2002/01/14 00:55:56 thorpej Exp $ + */ + +#include <sys/syscall.h> +#include <machine/asm.h> + +#define _SYSCALL(name) \ + .text; \ + .align 2; \ + li 0,(SYS_##name); \ + sc + +#ifndef _SYSCALL_BODY +#define _SYSCALL_BODY(name) \ + _SYSCALL(name); \ + bnslr; \ + mflr %r0; \ + std %r0,16(%r1); \ + stdu %r1,-48(%r1); \ + bl CNAME(HIDENAME(cerror)); \ + nop; \ + addi %r1,%r1,48; \ + ld %r0,16(%r1); \ + mtlr %r0; \ + blr +#endif + +#define PSEUDO(name) \ + .text; \ + .align 2; \ +ENTRY(__sys_##name); \ + WEAK_REFERENCE(__sys_##name, _##name); \ + _SYSCALL_BODY(name); \ +END(__sys_##name) + +#define RSYSCALL(name) \ + .text; \ + .align 2; \ +ENTRY(__sys_##name); \ + WEAK_REFERENCE(__sys_##name, name); \ + WEAK_REFERENCE(__sys_##name, _##name); \ + _SYSCALL_BODY(name); \ +END(__sys_##name) diff --git a/lib/libsys/powerpc64/__vdso_gettc.c b/lib/libsys/powerpc64/__vdso_gettc.c new file mode 100644 index 000000000000..c1de60a5b956 --- /dev/null +++ b/lib/libsys/powerpc64/__vdso_gettc.c @@ -0,0 +1,62 @@ +/*- + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (c) 2020 Brandon Bergren <bdragon@FreeBSD.org> + * + * This software was developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * 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. + */ + +#include <sys/types.h> +#include <sys/elf.h> +#include <sys/time.h> +#include <sys/vdso.h> + +#include <machine/cpufunc.h> + +#include <errno.h> + +#include "libc_private.h" + +#pragma weak __vdso_gettc +int +__vdso_gettc(const struct vdso_timehands *th, u_int *tc) +{ + u_quad_t tb; + + if (__predict_false(th->th_algo != VDSO_TH_ALGO_PPC_TB)) + return (ENOSYS); + + __asm __volatile ("mftb %0" : "=r"(tb)); + *tc = tb; + return (0); +} + +#pragma weak __vdso_gettimekeep +int +__vdso_gettimekeep(struct vdso_timekeep **tk) +{ + + return (_elf_aux_info(AT_TIMEKEEP, tk, sizeof(*tk))); +} diff --git a/lib/libsys/powerpc64/cerror.S b/lib/libsys/powerpc64/cerror.S new file mode 100644 index 000000000000..2be58cf8a84b --- /dev/null +++ b/lib/libsys/powerpc64/cerror.S @@ -0,0 +1,59 @@ +/*- + * Copyright (c) 2002 Peter Grehan. + * All rights reserved. + * + * 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. + */ +/* $NetBSD: cerror.S,v 1.5 2000/01/27 14:58:48 kleink Exp $ */ + +#include <machine/asm.h> +#include "SYS.h" + + .globl HIDENAME(cerror) + .globl CNAME(__error) + + /* + * The __error() function is thread aware. For non-threaded + * programs and the initial thread in threaded programs, + * it returns a pointer to the global errno variable. + */ +ENTRY_NOPROF(HIDENAME(cerror)) + mflr %r0 + std %r0,16(%r1) /* save lr */ + stdu %r1,-64(%r1) /* allocate new stack frame */ + std %r31,48(%r1) + + mr %r31,%r3 /* stash errval in callee-saved register */ + bl CNAME(__error) + nop + stw %r31,0(%r3) /* store errval into &errno */ + + ld %r31,48(%r1) + ld %r1,0(%r1) + ld %r0,16(%r1) + mtlr %r0 + li %r3,-1 + li %r4,-1 + blr +END(HIDENAME(cerror)) + + .section .note.GNU-stack,"",%progbits diff --git a/lib/libsys/powerpcspe/Makefile.sys b/lib/libsys/powerpcspe/Makefile.sys new file mode 100644 index 000000000000..35909d68cd5e --- /dev/null +++ b/lib/libsys/powerpcspe/Makefile.sys @@ -0,0 +1,5 @@ +CFLAGS+= -I${LIBC_SRCTOP}/powerpc +CFLAGS+= -I${LIBSYS_SRCTOP}/powerpc + +.PATH: ${LIBSYS_SRCTOP}/powerpc +.include "${LIBSYS_SRCTOP}/powerpc/Makefile.sys" diff --git a/lib/libsys/procctl.2 b/lib/libsys/procctl.2 new file mode 100644 index 000000000000..dfb7931de265 --- /dev/null +++ b/lib/libsys/procctl.2 @@ -0,0 +1,971 @@ +.\" Copyright (c) 2013 Hudson River Trading LLC +.\" Written by: John H. Baldwin <jhb@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Copyright (c) 2014 The FreeBSD Foundation +.\" Portions of this documentation were written by Konstantin Belousov +.\" under sponsorship from the FreeBSD Foundation. +.\" +.\" 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. +.\" +.Dd April 21, 2025 +.Dt PROCCTL 2 +.Os +.Sh NAME +.Nm procctl +.Nd control processes +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/procctl.h +.Ft int +.Fn procctl "idtype_t idtype" "id_t id" "int cmd" "void *data" +.Sh DESCRIPTION +The +.Fn procctl +system call provides for control over processes. +The +.Fa idtype +and +.Fa id +arguments specify the set of processes to control. +If multiple processes match the identifier, +.Nm +will make a +.Dq best effort +to control as many of the selected processes as possible. +An error is only returned if no selected processes successfully complete +the request. +The following identifier types are supported: +.Bl -tag -width P_PGID +.It Dv P_PID +Control the process with the process ID +.Fa id . +.Fa id +zero is a shortcut for the calling process ID. +.It Dv P_PGID +Control processes belonging to the process group with the ID +.Fa id . +.El +.Pp +The control request to perform is specified by the +.Fa cmd +argument. +.Pp +All status changing requests +.Pq Dv *_CTL +require the caller to have the right to debug the target. +All status query requests +.Pq Dv *_STATUS +require the caller to have the right to observe the target. +.Pp +The following commands are supported: +.Bl -tag -width PROC_LOGSIGEXIT_STATUS +.It Dv PROC_ASLR_CTL +Controls Address Space Layout Randomization (ASLR) in program +images created +by +.Xr execve 2 +in the specified process or its descendants that do not either change +the control or modify it by other means. +The +.Fa data +parameter must point to an integer variable holding one of the following +values: +.Bl -tag -width Ds +.It Dv PROC_ASLR_FORCE_ENABLE +Request that ASLR is enabled after execution, even if it is disabled +system-wide. +.It Dv PROC_ASLR_FORCE_DISABLE +Request that ASLR is disabled after execution, even if it is enabled +system-wide. +.It Dv PROC_ASLR_NOFORCE +Use the system-wide configured policy for ASLR. +.El +.Pp +Note that the +.Xr elfctl 1 +.Dq noaslr +flag takes precedence over this control. +Executing a binary with this flag set will never use ASLR. +Similarly, executing a set-user-ID or set-group-ID binary ignores this +control and only honors the +.Xr elfctl 1 +flag and system-wide policy. +.It Dv PROC_ASLR_STATUS +Returns the current status of ASLR enablement for the target process. +The +.Fa data +parameter must point to an integer variable, where one of the +following values is written: +.Bl -tag -width Ds +.It Dv PROC_ASLR_FORCE_ENABLE +.It Dv PROC_ASLR_FORCE_DISABLE +.It Dv PROC_ASLR_NOFORCE +.El +.Pp +If the currently executed image in the process itself has ASLR enabled, +the +.Dv PROC_ASLR_ACTIVE +flag is or-ed with the value listed above. +.It Dv PROC_LOGSIGEXIT_CTL +Controls the logging of exits due to signals that would normally cause a core +dump. +The +.Va arg +parameter must point to an integer variable holding one of the following values: +.Bl -tag -width PROC_LOGSIGEXIT_CTL_FORCE_DISABLE +.It Dv PROC_LOGSIGEXIT_CTL_FORCE_ENABLE +Enables logging of exits due to signals that would normally cause a core dump. +Logging is done via +.Xr log 9 +with a log level of +.Dv LOG_INFO . +.It Dv PROC_LOGSIGEXIT_CTL_FORCE_DISABLE +Disables the logging of exits due to signals that would normally cause a core +dump. +.It Dv PROC_LOGSIGEXIT_CTL_NOFORCE +The logging behavior is delegated to the +.Xr sysctl 3 +MIB variable +.Va kern.logsigexit . +.El +.It Dv PROC_LOGSIGEXIT_STATUS +Returns the current status of logging for the target process. +The +.Va arg +parameter must point to an integer variable, where one of the following values +is written: +.Bl -tag -width PROC_LOGSIGEXIT_CTL_FORCE_DISABLE +.It Dv PROC_LOGSIGEXIT_CTL_FORCE_ENABLE +.It Dv PROC_LOGSIGEXIT_CTL_FORCE_DISABLE +.It Dv PROC_LOGSIGEXIT_CTL_NOFORCE +.El +.It Dv PROC_PROTMAX_CTL +Controls the maximum protection used for +.Xr mmap 2 +requests in the target process that do not specify +an explicit maximum protection in the +.Fa prot +argument via +.Dv PROT_MAX . +The maximum protection limits the permissions a mapping can be assigned by +.Xr mprotect 2 . +If an explicit maximum protection is not provided, +the maximum protection for a new mapping is set to either +.Dv PROT_READ | PROT_WRITE | PROT_EXEC +.Pq RWX +or the protection specified in +.Fa prot . +Mappings created with +.Fa prot +set to +.Dv PROT_NONE +always use RWX maximum protection. +.Pp +The +.Fa data +parameter must point to an integer variable holding one of the following +values: +.Bl -tag -width Ds +.It Dv PROC_PROTMAX_FORCE_ENABLE +Use the permissions in +.Fa prot +as the implicit maximum protection, +even if RWX permissions are requested by the sysctl +.Va vm.imply_prot_max . +.It Dv PROC_PROTMAX_FORCE_DISABLE +Use RWX as the implicit maximum protection, +even if constrained permissions are requested by the sysctl +.Va vm.imply_prot_max . +.It Dv PROC_PROTMAX_NOFORCE +Use the system-wide configured policy for the implicit PROT_MAX control. +.El +.Pp +Note that the +.Xr elfctl 1 +.Dq noprotmax +flag takes precedence over this control. +Executing a binary with this flag set will always use RWX as the implicit +maximum protection. +.It Dv PROC_PROTMAX_STATUS +Returns the current status of the implicit PROT_MAX control for the +target process. +The +.Fa data +parameter must point to an integer variable, where one of the +following values is written: +.Bl -tag -width Ds +.It Dv PROC_PROTMAX_FORCE_ENABLE +.It Dv PROC_PROTMAX_FORCE_DISABLE +.It Dv PROC_PROTMAX_NOFORCE +.El +.Pp +If the currently executed image in the process itself has the implicit PROT_MAX +control enabled, the +.Dv PROC_PROTMAX_ACTIVE +flag is or-ed with the value listed above. +.It Dv PROC_SPROTECT +Set process protection state. +This is used to mark a process as protected from being killed if the system +exhausts available memory and swap. +The +.Fa data +parameter must point to an integer containing an operation and zero or more +optional flags. +The following operations are supported: +.Bl -tag -width Ds +.It Dv PPROT_SET +Mark the selected processes as protected. +.It Dv PPROT_CLEAR +Clear the protected state of selected processes. +.El +.Pp +The following optional flags are supported: +.Bl -tag -width Ds +.It Dv PPROT_DESCEND +Apply the requested operation to all child processes of each selected process +in addition to each selected process. +.It Dv PPROT_INHERIT +When used with +.Dv PPROT_SET , +mark all future child processes of each selected process as protected. +Future child processes will also mark all of their future child processes. +.El +.It Dv PROC_REAP_ACQUIRE +Enable orphaned process reaping for future children of the current process. +.Pp +If a parent process exits before one or more of its children processes, +the remaining children processes are orphaned. +When an orphaned process exits, +it is reparented to a reaper process that is responsible for harvesting +the terminated process via +.Xr wait 2 . +When this control is enabled, +the current process becomes the reaper process for future children and their +descendants. +Existing child processes continue to use the reaper assigned when the child +was created via +.Xr fork 2 . +If a reaper process exits, +all of the processes for whom it was the reaper are reassigned to the reaper +process's reaper. +.Pp +After system initialization, +.Xr init 8 +is the default reaper. +.It Dv PROC_REAP_RELEASE +Disable orphaned process reaping for the current process. +.Pp +Any processes for whom the current process was the reaper are reassigned to +the current process's reaper. +.It Dv PROC_REAP_STATUS +Provides a consistent snapshot of information about the reaper +of the specified process, +or the process itself if it is a reaper. +The +.Fa data +argument must point to a +.Vt procctl_reaper_status +structure which is filled in by the system call on successful return. +.Bd -literal +struct procctl_reaper_status { + u_int rs_flags; + u_int rs_children; + u_int rs_descendants; + pid_t rs_reaper; + pid_t rs_pid; +}; +.Ed +.Pp +The +.Fa rs_flags +may have the following flags returned: +.Bl -tag -width Ds +.It Dv REAPER_STATUS_OWNED +The specified process is a reaper. +When this flag is returned, the specified process +.Fa id , +pid, identifies a reaper, otherwise the +.Fa rs_reaper +field of the structure is set to the pid of the reaper +for the specified process id. +.It Dv REAPER_STATUS_REALINIT +The specified process is the root of the reaper tree, i.e., +.Xr init 8 . +.El +.Pp +The +.Fa rs_children +field returns the number of processes that can be reaped by the reaper that +are also children of the reaper. +It is possible to have a child whose reaper is not the specified process, +since the reaper for existing children is not changed by +.Dv PROC_REAP_ACQUIRE . +The +.Fa rs_descendants +field returns the total number of processes that can be reaped by the reaper. +The +.Fa rs_reaper +field returns the reaper's pid. +The +.Fa rs_pid +returns the pid of one reaper child if there are any processes that can be +reapead; +otherwise, it is set to \-1. +.It Dv PROC_REAP_GETPIDS +Queries the list of processes that can be reaped +by the reaper of the specified process. +The request takes a pointer to a +.Vt procctl_reaper_pids +structure in the +.Fa data +parameter. +.Bd -literal +struct procctl_reaper_pids { + u_int rp_count; + struct procctl_reaper_pidinfo *rp_pids; +}; +.Ed +.Pp +When called, the +.Fa rp_pids +field must point to an array of +.Fa rp_count +.Vt procctl_reaper_pidinfo +structures. +The kernel will populate these structures with information about the +reaper's descendants. +.Pp +The +.Vt "struct procctl_reaper_pidinfo" +structure provides some information about one of the reaper's descendants. +Note that for a descendant that is not a child, it may be incorrectly +identified because of a race in which the original child process exited +and the exited process's pid was reused for an unrelated process. +.Bd -literal +struct procctl_reaper_pidinfo { + pid_t pi_pid; + pid_t pi_subtree; + u_int pi_flags; +}; +.Ed +.Pp +The +.Fa pi_pid +field is the process id of the descendant. +The +.Fa pi_subtree +field provides the pid of the direct child of the reaper which is +the (grand-)parent of the descendant process. +The +.Fa pi_flags +field returns the following flags, further describing the descendant: +.Bl -tag -width Ds +.It Dv REAPER_PIDINFO_VALID +Set to indicate that the +.Vt procctl_reaper_pidinfo +structure was filled in by the kernel. +Zero-filling the +.Fa rp_pids +array and testing the +.Dv REAPER_PIDINFO_VALID +flag allows the caller to detect the end +of the returned array. +.It Dv REAPER_PIDINFO_CHILD +The +.Fa pi_pid +field identifies a direct child of the reaper. +.It Dv REAPER_PIDINFO_REAPER +The reported process is itself a reaper. +The descendants of the subordinate reaper are not reported. +.It Dv REAPER_PIDINFO_ZOMBIE +The reported process is in the zombie state, ready to be reaped. +.It Dv REAPER_PIDINFO_STOPPED +The reported process is stopped by a SIGSTOP/SIGTSTP signal. +.It Dv REAPER_PIDINFO_EXITING +The reported process is in the process of exiting (but not yet a zombie). +.El +.It Dv PROC_REAP_KILL +Request to deliver a signal to some subset of the descendants of the reaper. +The +.Fa data +parameter must point to a +.Vt procctl_reaper_kill +structure, which is used both for parameters and status return. +.Bd -literal +struct procctl_reaper_kill { + int rk_sig; + u_int rk_flags; + pid_t rk_subtree; + u_int rk_killed; + pid_t rk_fpid; +}; +.Ed +.Pp +The +.Fa rk_sig +field specifies the signal to be delivered. +Zero is not a valid signal number, unlike for +.Xr kill 2 . +The +.Fa rk_flags +field further directs the operation. +It is or-ed from the following flags: +.Bl -tag -width Ds +.It Dv REAPER_KILL_CHILDREN +Deliver the specified signal only to direct children of the reaper. +.It Dv REAPER_KILL_SUBTREE +Deliver the specified signal only to descendants that were forked by +the direct child with pid specified in the +.Fa rk_subtree +field. +.El +.Pp +If neither the +.Dv REAPER_KILL_CHILDREN +nor the +.Dv REAPER_KILL_SUBTREE +flags are specified, all current descendants of the reaper are signalled. +.Pp +If a signal was delivered to any process, the return value from the request +is zero. +In this case, the +.Fa rk_killed +field identifies the number of processes signalled. +The +.Fa rk_fpid +field is set to the pid of the first process for which signal +delivery failed, e.g., due to permission problems. +If no such process exists, the +.Fa rk_fpid +field is set to \-1. +.It Dv PROC_TRACE_CTL +Enable or disable tracing of the specified process(es), according to the +value of the integer argument. +Tracing includes inspecting the process via +.Xr ptrace 2 , +.Xr ktrace 2 , +debugging sysctls, +.Xr hwpmc 4 , +or +.Xr dtrace 1 +as well as dumping core. +Possible values for the +.Fa data +argument are: +.Bl -tag -width Ds +.It Dv PROC_TRACE_CTL_ENABLE +Enable tracing, after it was disabled by +.Dv PROC_TRACE_CTL_DISABLE . +Only allowed for self. +.It Dv PROC_TRACE_CTL_DISABLE +Disable tracing for the specified process. +Tracing is re-enabled when the process changes the executing +program with the +.Xr execve 2 +system call. +A child inherits the trace settings from the parent on +.Xr fork 2 . +.It Dv PROC_TRACE_CTL_DISABLE_EXEC +Same as +.Dv PROC_TRACE_CTL_DISABLE , +but the setting persists for the process even after +.Xr execve 2 . +.El +.It Dv PROC_TRACE_STATUS +Returns the current tracing status for the specified process in +the integer variable pointed to by +.Fa data . +If tracing is disabled, +.Fa data +is set to \-1. +If tracing is enabled, but no debugger is attached by the +.Xr ptrace 2 +system call, +.Fa data +is set to 0. +If a debugger is attached, +.Fa data +is set to the pid of the debugger process. +.It Dv PROC_TRAPCAP_CTL +Controls the capability mode sandbox actions for the specified +sandboxed processes +on a return from any system call which fails with either an +.Er ENOTCAPABLE +or +.Er ECAPMODE +error. +If this control is enabled and a system call fails with one of these errors, +a synchronous +.Dv SIGTRAP +signal is delivered to the thread immediately before returning from the +system call. +.Pp +Possible values for the +.Fa data +argument are: +.Bl -tag -width Ds +.It Dv PROC_TRAPCAP_CTL_ENABLE +Enable +.Dv SIGTRAP +signal delivery on capability mode access violations. +The enabled mode is inherited by the children of the process, +and is kept after +.Xr fexecve 2 +calls. +.It Dv PROC_TRAPCAP_CTL_DISABLE +Disable +.Dv SIGTRAP +signal delivery on capability mode access violations. +Note that the global sysctl +.Dv kern.trap_enotcap +might still cause the signal to be delivered. +See +.Xr capsicum 4 . +.El +.Pp +On signal delivery, the +.Va si_errno +member of the +.Fa siginfo +signal handler parameter is set to the system call error value, +and the +.Va si_code +member is set to +.Dv TRAP_CAP . +The system call number is stored in the +.Va si_syscall +field of the +.Fa siginfo +signal handler parameter. +The other system call parameters can be read from the +.Fa ucontext_t +but the system call number is typically stored in the register +that also contains the return value and so is unavailable in the +signal handler. +.Pp +See +.Xr capsicum 4 +for more information about capability mode. +.It Dv PROC_TRAPCAP_STATUS +Return the current status of raising +.Dv SIGTRAP +for capability mode access violations by the specified process. +The integer value pointed to by the +.Fa data +argument is set to the +.Dv PROC_TRAPCAP_CTL_ENABLE +value if +.Dv SIGTRAP +delivery is enabled, and to +.Dv PROC_TRAPCAP_CTL_DISABLE +otherwise. +.Pp +See the note about sysctl +.Dv kern.trap_enotcap +above, which gives independent global control of signal delivery. +.It Dv PROC_PDEATHSIG_CTL +Request the delivery of a signal when the parent of the calling +process exits. +.Fa idtype +must be +.Dv P_PID +and +.Fa id +must be the either caller's pid or zero, with no difference in effect. +The value is cleared for child processes +and when executing set-user-ID or set-group-ID binaries. +.Fa data +must point to a value of type +.Vt int +indicating the signal +that should be delivered to the caller. +Use zero to cancel a previously requested signal delivery. +.It Dv PROC_PDEATHSIG_STATUS +Query the current signal number that will be delivered when the parent +of the calling process exits. +.Fa idtype +must be +.Dv P_PID +and +.Fa id +must be the either caller's pid or zero, with no difference in effect. +.Fa data +must point to a memory location that can hold a value of type +.Vt int . +If signal delivery has not been requested, it will contain zero +on return. +.It Dv PROC_STACKGAP_CTL +Controls stack gaps in the specified process. +A stack gap is one or more virtual memory pages at the end of the +growth area for a +.Dv MAP_STACK +mapping that is reserved and never backed by memory. +Instead, the process is guaranteed to receive a synchronous +.Dv SIGSEGV +signal for each access to pages in the gap. +The number of pages reserved for each stack is set by the sysctl +.Va security.bsd.stack_guard_page . +.Pp +Gaps protect against stack overflows by preventing them from corrupting memory +adjacent to the stack. +.Pp +The +.Fa data +argument must point to an integer variable containing flags. +The following flags are allowed: +.Bl -tag -width Ds +.It Dv PROC_STACKGAP_ENABLE +This flag is only accepted for consistency with +.Dv PROC_STACKGAP_STATUS . +If stack gaps are enabled, the flag is ignored. +If stack gaps are disabled, the request fails with +.Ev EINVAL . +After gaps are disabled in a process, they can only be re-enabled when an +.Xr execve 2 +is performed. +.It Dv PROC_STACKGAP_DISABLE +Disable stack gaps for the process. +For existing stacks, the gap is no longer reserved +and can be filled by memory on access. +.It Dv PROC_STACKGAP_ENABLE_EXEC +Enable stack gaps for the new address space constructed by any future +.Xr execve 2 +in the specified process. +.It Dv PROC_STACKGAP_DISABLE_EXEC +Inherit disabled stack gaps state after +.Xr execve 2 . +In other words, if the currently executing program has stack gaps disabled, +they are kept disabled on exec. +If gaps were enabled, they are kept enabled after exec. +.El +.Pp +The stack gap state is inherited from the parent on +.Xr fork 2 . +.It Dv PROC_STACKGAP_STATUS +Returns the current stack gap state for the specified process. +.Fa data +must point to an integer variable, which is used to return a bitmask +consisting of the following flags: +.Bl -tag -width Ds +.It Dv PROC_STACKGAP_ENABLE +Stack gaps are enabled. +.It Dv PROC_STACKGAP_DISABLE +Stack gaps are disabled. +.It Dv PROC_STACKGAP_ENABLE_EXEC +Stack gaps are enabled in the process after +.Xr execve 2 . +.It Dv PROC_STACKGAP_DISABLE_EXEC +Stack gaps are disabled in the process after +.Xr execve 2 . +.El +.Pp +Note that the +.Xr elfctl 1 +.Dq nostackgap +flag takes precedence over this setting for individual process address spaces. +Executing a binary with this flag set will never use stack gaps in the address +space constructed by +.Xr execve 2 . +However, the controls value can still be inherited by child processes, and +executing a binary without this flag set will revert to the behavior specified +by the control. +.It Dv PROC_NO_NEW_PRIVS_CTL +Allows one to ignore the set-user-ID and set-group-ID bits on the program +images activated by +.Xr execve 2 +in the specified process and its future descendants. +The +.Fa data +parameter must point to an integer variable holding the following +value: +.Bl -tag -width Ds +.It Dv PROC_NO_NEW_PRIVS_ENABLE +Request set-user-ID and set-group-ID bits to be ignored. +.El +.Pp +It is not possible to disable this control once it has been enabled. +.It Dv PROC_NO_NEW_PRIVS_STATUS +Returns the current status of set-ID bits enablement for the target process. +The +.Fa data +parameter must point to an integer variable, where one of the +following values is written: +.Bl -tag -width Ds +.It Dv PROC_NO_NEW_PRIVS_ENABLE +.It Dv PROC_NO_NEW_PRIVS_DISABLE +.El +.It Dv PROC_WXMAP_CTL +Controls the creation of mappings with both write and execute permissions +in a process's address space. +The +.Fa data +parameter must point to an integer variable holding one of the +following values: +.Bl -tag -width Ds +.It Dv PROC_WX_MAPPINGS_PERMIT +Enable creation of mappings that have both write and execute +permissions in the specified process' current and future address spaces. +.It Dv PROC_WX_MAPPINGS_DISALLOW_EXEC +In a new address space created by a future call to +.Xr execve 2 , +disallow creation of mappings that have both write and execute +permissions. +.El +.Pp +If both flags are set, +.Dv PROC_WX_MAPPINGS_DISALLOW_EXEC +takes precedence during +.Xr execve 2 . +If neither flag is set, +mappings with write and execute permissions are only permitted if the +.Dv kern.elf{32/64}.allow_wx +sysctl is non-zero or the +.Xr elfctl 1 +.Dq wxneeded +flag is set in the ELF control note. +.Pp +Once creation of writeable and executable mappings is enabled for a process, +it is impossible (and pointless) to disable it. +The only way to ensure the absence of such mappings after they +were enabled in a given process is to set the +.Dv PROC_WX_MAPPINGS_DISALLOW_EXEC +flag and +.Xr execve 2 +an image. +.It Dv PROC_WXMAP_STATUS +Returns the current status of the controls over creation of mappings with +both write and execute permissions for the specified process. +The +.Dv data +parameter must point to an integer variable, where one of the +following values is written: +.Bl -tag -width Ds +.It Dv PROC_WX_MAPPINGS_PERMIT +Creation of simultaneously writable and executable mappings are permitted; +otherwise, the process cannot create such mappings. +.It Dv PROC_WX_MAPPINGS_DISALLOW_EXEC +After +.Xr execve 2 , +the new address space will not permit creation of simultaneously +writable and executable mappings. +.El +.Pp +Additionally, if the address space of the process does not permit +creation of simultaneously writable and executable mappings and +it is guaranteed that no such mapping was created since address space +creation, the +.Dv PROC_WXORX_ENFORCE +flag is set in the returned value. +.El +.Sh x86 MACHINE-SPECIFIC REQUESTS +.Bl -tag -width PROC_KPTI_STATUS +.It Dv PROC_KPTI_CTL +AMD64 only. +Controls the Kernel Page Table Isolation (KPTI) option for the children +of the specified process. +This control is only meaningful if KPTI has been enabled globally by the +.Va vm.pmap.kpti +tunable. +It is not possible to change the KPTI setting for a running process, +only for new address spaces constructed by a future +.Xr execve 2 . +.Pp +The +.Fa data +parameter must point to an integer variable containing one of the +following commands: +.Bl -tag -width Ds +.It Dv PROC_KPTI_CTL_ENABLE_ON_EXEC +Enable KPTI after +.Xr execve 2 . +.It Dv PROC_KPTI_CTL_DISABLE_ON_EXEC +Disable KPTI after +.Xr execve 2 . +Only root or a process having the +.Va PRIV_IO +privilege can use this option. +.El +.It Dv PROC_KPTI_STATUS +Returns the current KPTI status for the specified process. +.Fa data +must point to an integer variable, where one of the +following values is written: +.Bl -tag -width Ds +.It Dv PROC_KPTI_CTL_ENABLE_ON_EXEC +.It Dv PROC_KPTI_CTL_DISABLE_ON_EXEC +.El +.Pp +The status is or-ed with +.Va PROC_KPTI_STATUS_ACTIVE +if KPTI is active for the current address space of the process. +.El +.Sh NOTES +Disabling tracing on a process should not be considered a security +feature, as it is bypassable both by the kernel and privileged processes +and via other system mechanisms. +As such, it should not be utilized to reliably protect cryptographic +keying material or other confidential data. +.Pp +Note that processes can trivially bypass the 'no simultaneously +writable and executable mappings' policy by first marking some mapping +as writeable, writing code to it, then removing write and adding +execute permission. +This may be legitimately required by some programs such as JIT compilers. +.Sh RETURN VALUES +If an error occurs, a value of \-1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn procctl +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EFAULT +The +.Fa data +parameter points outside the process's allocated address space. +.It Bq Er EINVAL +The +.Fa cmd +argument specifies an unsupported command. +.Pp +The +.Fa idtype +argument specifies an unsupported identifier type. +.It Bq Er EPERM +The calling process does not have permission to perform the requested +operation on any of the selected processes. +.It Bq Er ESRCH +No processes matched the requested +.Fa idtype +and +.Fa id . +.It Bq Er ESRCH +No descendant processes can be found matching criteria specified in the +.Dv PROC_REAP_KILL +request. +.It Bq Er EINVAL +An invalid operation or flag was passed in +.Fa data +for a +.Dv PROC_SPROTECT +command. +.It Bq Er EPERM +The +.Fa idtype +argument is not equal to +.Dv P_PID , +or +.Fa id +is not equal to the pid of the calling process, for +.Dv PROC_REAP_ACQUIRE +or +.Dv PROC_REAP_RELEASE +requests. +.It Bq Er EINVAL +Invalid or undefined flags were passed to a +.Dv PROC_REAP_KILL +request. +.It Bq Er EINVAL +An invalid or zero signal number was requested for a +.Dv PROC_REAP_KILL +request. +.It Bq Er EINVAL +A +.Dv PROC_REAP_RELEASE +request was issued by the +.Xr init 8 +process. +.It Bq Er EBUSY +A +.Dv PROC_REAP_ACQUIRE +request was issued by a process that is already a reaper process. +.It Bq Er EBUSY +A +.Dv PROC_TRACE_CTL +request was issued for a process being traced. +.It Bq Er EPERM +A +.Dv PROC_TRACE_CTL +request to re-enable tracing of the process +.Po Dv PROC_TRACE_CTL_ENABLE Pc , +or to disable persistence of +.Dv PROC_TRACE_CTL_DISABLE +on +.Xr execve 2 +specified a target process other than the calling process. +.It Bq Er EINVAL +The value of the integer +.Fa data +parameter for the +.Dv PROC_TRACE_CTL +or +.Dv PROC_TRAPCAP_CTL +request is invalid. +.It Bq Er EINVAL +The +.Dv PROC_PDEATHSIG_CTL +or +.Dv PROC_PDEATHSIG_STATUS +request referenced an unsupported +.Fa id , +.Fa idtype +or invalid signal number. +.El +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr elfctl 1 , +.Xr proccontrol 1 , +.Xr protect 1 , +.Xr cap_enter 2 , +.Xr kill 2 , +.Xr ktrace 2 , +.Xr mmap 2 , +.Xr mprotect 2 , +.Xr ptrace 2 , +.Xr wait 2 , +.Xr capsicum 4 , +.Xr hwpmc 4 , +.Xr init 8 +.Sh HISTORY +The +.Fn procctl +function appeared in +.Fx 9.3 . +.Pp +The reaper facility is based on a similar feature in Linux and +DragonflyBSD, and first appeared in +.Fx 10.2 . +.Pp +The +.Dv PROC_PDEATHSIG_CTL +facility is based on the +.Ql prctl(PR_SET_PDEATHSIG, ...) +feature in Linux, +and first appeared in +.Fx 11.2 . +.Pp +ASLR support was added for checklist compliance in +.Fx 13.0 . diff --git a/lib/libsys/profil.2 b/lib/libsys/profil.2 new file mode 100644 index 000000000000..025b6b7e7802 --- /dev/null +++ b/lib/libsys/profil.2 @@ -0,0 +1,119 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Donn Seeley of BSDI. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd December 1, 2017 +.Dt PROFIL 2 +.Os +.Sh NAME +.Nm profil +.Nd control process profiling +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn profil "char *samples" "size_t size" "vm_offset_t offset" "int scale" +.Sh DESCRIPTION +The +.Fn profil +system call enables or disables +program counter profiling of the current process. +If profiling is enabled, +then at every profiling clock tick, +the kernel updates an appropriate count in the +.Fa samples +buffer. +The frequency of the profiling clock is recorded +in the header in the profiling output file. +.Pp +The buffer +.Fa samples +contains +.Fa size +bytes and is divided into +a series of 16-bit bins. +Each bin counts the number of times the program counter +was in a particular address range in the process +when a profiling clock tick occurred while profiling was enabled. +For a given program counter address, +the number of the corresponding bin is given +by the relation: +.Bd -literal -offset indent +[(pc - offset) / 2] * scale / 65536 +.Ed +.Pp +The +.Fa offset +argument is the lowest address at which +the kernel takes program counter samples. +The +.Fa scale +argument ranges from 1 to 65536 and +can be used to change the span of the bins. +A scale of 65536 maps each bin to 2 bytes of address range; +a scale of 32768 gives 4 bytes, 16384 gives 8 bytes and so on. +Intermediate values provide approximate intermediate ranges. +A +.Fa scale +value of 0 disables profiling. +.Sh RETURN VALUES +.Rv -std profil +.Sh FILES +.Bl -tag -width /usr/lib/gcrt0.o -compact +.It Pa /usr/lib/gcrt0.o +profiling C run-time startup file +.It Pa gmon.out +conventional name for profiling output file +.El +.Sh ERRORS +The following error may be reported: +.Bl -tag -width Er +.It Bq Er EFAULT +The buffer +.Fa samples +contains an invalid address. +.El +.Sh SEE ALSO +.Xr gprof 1 +.Sh HISTORY +The +.Fn profil +functionality first appeared in +.At v3 . +.Sh BUGS +This routine should be named +.Fn profile . +.Pp +The +.Fa samples +argument should really be a vector of type +.Fa "unsigned short" . +.Pp +The format of the gmon.out file is undocumented. diff --git a/lib/libsys/pselect.2 b/lib/libsys/pselect.2 new file mode 100644 index 000000000000..29e6d8602d4f --- /dev/null +++ b/lib/libsys/pselect.2 @@ -0,0 +1,128 @@ +.\" +.\" Copyright 2002 Massachusetts Institute of Technology +.\" +.\" Permission to use, copy, modify, and distribute this software and +.\" its documentation for any purpose and without fee is hereby +.\" granted, provided that both the above copyright notice and this +.\" permission notice appear in all copies, that both the above +.\" copyright notice and this permission notice appear in all +.\" supporting documentation, and that the name of M.I.T. not be used +.\" in advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. M.I.T. makes +.\" no representations about the suitability of this software for any +.\" purpose. It is provided "as is" without express or implied +.\" warranty. +.\" +.\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS +.\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE, +.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT +.\" SHALL M.I.T. 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. +.\" +.Dd July 2, 2022 +.Dt PSELECT 2 +.Os +.Sh NAME +.Nm pselect +.Nd synchronous I/O multiplexing a la POSIX.1g +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/select.h +.Ft int +.Fo pselect +.Fa "int nfds" +.Fa "fd_set * restrict readfds" +.Fa "fd_set * restrict writefds" +.Fa "fd_set * restrict exceptfds" +.Fa "const struct timespec * restrict timeout" +.Fa "const sigset_t * restrict newsigmask" +.Fc +.Sh DESCRIPTION +The +.Fn pselect +function was introduced by +.St -p1003.1g-2000 +as a slightly stronger version of +.Xr select 2 . +The +.Fa nfds , readfds , writefds , +and +.Fa exceptfds +arguments are all identical to the analogous arguments of +.Fn select . +The +.Fa timeout +argument in +.Fn pselect +points to a +.Vt "const struct timespec" +rather than the potentially modifiable +.Vt "struct timeval" +used by +.Fn select ; +as in +.Fn select , +a null pointer may be passed to indicate that +.Fn pselect +should wait indefinitely. +Finally, +.Fa newsigmask +specifies a signal mask which is set while waiting for input. +When +.Fn pselect +returns, the original signal mask is restored. +If +.Fa newsigmask +is a null pointer, +.Fn pselect +behaves like +.Fn select +with no setting or restoration of the signal mask. +.Pp +See +.Xr select 2 +for a more detailed discussion of the semantics of this interface, and +for macros used to manipulate the +.Vt "fd_set" +data type. +.Sh RETURN VALUES +The +.Fn pselect +function returns the same values and under the same conditions as +.Fn select . +.Sh ERRORS +The +.Fn pselect +function may fail for any of the reasons documented for +.Xr select 2 +and (if a signal mask is provided) +.Xr sigprocmask 2 . +.Sh SEE ALSO +.Xr kqueue 2 , +.Xr poll 2 , +.Xr select 2 , +.Xr sigprocmask 2 , +.Xr sigsuspend 2 +.Sh STANDARDS +The +.Fn pselect +function conforms to +.St -p1003.1-2001 . +.Sh HISTORY +The +.Fn pselect +function first appeared in +.Fx 5.0 . +.Sh AUTHORS +The first implementation of +.Fn pselect +function and this manual page were written by +.An Garrett Wollman Aq Mt wollman@FreeBSD.org . diff --git a/lib/libsys/ptrace.2 b/lib/libsys/ptrace.2 new file mode 100644 index 000000000000..7aa24a3f820b --- /dev/null +++ b/lib/libsys/ptrace.2 @@ -0,0 +1,1451 @@ +.\" $NetBSD: ptrace.2,v 1.2 1995/02/27 12:35:37 cgd Exp $ +.\" +.\" This file is in the public domain. +.Dd June 19, 2025 +.Dt PTRACE 2 +.Os +.Sh NAME +.Nm ptrace +.Nd process tracing and debugging +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/ptrace.h +.Ft int +.Fn ptrace "int request" "pid_t pid" "caddr_t addr" "int data" +.Sh DESCRIPTION +The +.Fn ptrace +system call +provides tracing and debugging facilities. +It allows one process +(the +.Em tracing +process) +to control another +(the +.Em traced +process). +The tracing process must first attach to the traced process, and then +issue a series of +.Fn ptrace +system calls to control the execution of the process, as well as access +process memory and register state. +For the duration of the tracing session, the traced process will be +.Dq re-parented , +with its parent process ID (and resulting behavior) +changed to the tracing process. +It is permissible for a tracing process to attach to more than one +other process at a time. +When the tracing process has completed its work, it must detach the +traced process; if a tracing process exits without first detaching all +processes it has attached, those processes will be killed. +.Pp +Most of the time, the traced process runs normally, but when it +receives a signal +(see +.Xr sigaction 2 ) , +it stops. +The tracing process is expected to notice this via +.Xr wait 2 +or the delivery of a +.Dv SIGCHLD +signal, examine the state of the stopped process, and cause it to +terminate or continue as appropriate. +The signal may be a normal process signal, generated as a result of +traced process behavior, or use of the +.Xr kill 2 +system call; alternatively, it may be generated by the tracing facility +as a result of attaching, stepping by the tracing +process, +or an event in the traced process. +The tracing process may choose to intercept the signal, using it to +observe process behavior (such as +.Dv SIGTRAP ) , +or forward the signal to the process if appropriate. +The +.Fn ptrace +system call +is the mechanism by which all this happens. +.Pp +A traced process may report additional signal stops corresponding to +events in the traced process. +These additional signal stops are reported as +.Dv SIGTRAP +or +.Dv SIGSTOP +signals. +The tracing process can use the +.Dv PT_LWPINFO +request to determine which events are associated with a +.Dv SIGTRAP +or +.Dv SIGSTOP +signal. +Note that multiple events may be associated with a single signal. +For example, events indicated by the +.Dv PL_FLAG_BORN , +.Dv PL_FLAG_FORKED , +and +.Dv PL_FLAG_EXEC +flags are also reported as a system call exit event +.Pq Dv PL_FLAG_SCX . +The signal stop for a new child process enabled via +.Dv PTRACE_FORK +will report a +.Dv SIGSTOP +signal. +All other additional signal stops use +.Dv SIGTRAP . +.Sh DETACH AND TERMINATION +.Pp +Normally, exiting tracing process should wait for all pending +debugging events and then detach from all alive traced processes +before exiting using +.Dv PT_DETACH +request. +If tracing process exits without detaching, for instance due to abnormal +termination, the destiny of the traced children processes is determined +by the +.Dv kern.kill_on_debugger_exit +sysctl control. +.Pp +If the control is set to the default value 1, such traced processes +are terminated. +If set to zero, kernel implicitly detaches traced processes. +Traced processes are un-stopped if needed, and then continue the execution +without tracing. +Kernel drops any +.Dv SIGTRAP +signals queued to the traced children, which could be either generated by +not yet consumed debug events, or sent by other means, the later should +not be done anyway. +.Sh SELECTING THE TARGET +The +.Fa pid +argument of the call specifies the target on which to perform +the requested operation. +For operations affecting the global process state, the process ID +is typically passed there. +Similarly, for operations affecting only a thread, the thread ID +needs to be passed. +.Pp +Still, for global operations, the ID of any thread can be used as the +target, and system will perform the request on the process owning +that thread. +If a thread operation got the process ID as +.Fa pid , +the system randomly selects a thread from among the threads owned +by the process. +For single-threaded processes there is no difference between specifying +process or thread ID as the target. +.Sh DISABLING PTRACE +The +.Nm +subsystem provides rich facilities to manipulate other processes state. +Sometimes it may be desirable to disallow it either completely, or limit +its scope. +The following controls are provided for this: +.Bl -tag -width security.bsd.unprivileged_proc_debug +.It Dv security.bsd.allow_ptrace +Setting this sysctl to zero makes +.Nm +return +.Er ENOSYS +always as if the syscall is not implemented by the kernel. +.It Dv security.bsd.unprivileged_proc_debug +Setting this sysctl to zero disallows the use of +.Fn ptrace +by unprivileged processes. +.It Dv security.bsd.see_other_uids +Setting this sysctl to zero prevents +.Fn ptrace +requests from targeting processes with a real user identifier different +from the caller's. +These requests will fail with error +.Er ESRCH . +.It Dv security.bsd.see_other_gids +Setting this sysctl to zero disallows +.Fn ptrace +requests from processes that have no groups in common with the target process, +considering their sets of real and supplementary groups. +These requests will fail with error +.Er ESRCH . +.It Dv security.bsd.see_jail_proc +Setting this sysctl to zero disallows +.Fn ptrace +requests from processes belonging to a different jail than that of the target +process, even if the requesting process' jail is an ancestor of the target +process'. +These requests will fail with error +.Er ESRCH . +.It Dv securelevel and init +The +.Xr init 1 +process can only be traced with +.Nm +if securelevel is zero. +.It Dv procctl(2) PROC_TRACE_CTL +Process can deny attempts to trace itself with +.Xr procctl 2 +.Dv PROC_TRACE_CTL +request. +In this case requests return +.Xr EPERM +error. +.El +.Sh TRACING EVENTS +.Pp +Each traced process has a tracing event mask. +An event in the traced process only reports a +signal stop if the corresponding flag is set in the tracing event mask. +The current set of tracing event flags include: +.Bl -tag -width "Dv PTRACE_SYSCALL" +.It Dv PTRACE_EXEC +Report a stop for a successful invocation of +.Xr execve 2 . +This event is indicated by the +.Dv PL_FLAG_EXEC +flag in the +.Va pl_flags +member of +.Vt "struct ptrace_lwpinfo" . +.It Dv PTRACE_SCE +Report a stop on each system call entry. +This event is indicated by the +.Dv PL_FLAG_SCE +flag in the +.Va pl_flags +member of +.Vt "struct ptrace_lwpinfo" . +.It Dv PTRACE_SCX +Report a stop on each system call exit. +This event is indicated by the +.Dv PL_FLAG_SCX +flag in the +.Va pl_flags +member of +.Vt "struct ptrace_lwpinfo" . +.It Dv PTRACE_SYSCALL +Report stops for both system call entry and exit. +.It Dv PTRACE_FORK +This event flag controls tracing for new child processes of a traced process. +.Pp +When this event flag is enabled, +new child processes will enable tracing and stop before executing their +first instruction. +The new child process will include the +.Dv PL_FLAG_CHILD +flag in the +.Va pl_flags +member of +.Vt "struct ptrace_lwpinfo" . +The traced process will report a stop that includes the +.Dv PL_FLAG_FORKED +flag. +The process ID of the new child process will also be present in the +.Va pl_child_pid +member of +.Vt "struct ptrace_lwpinfo" . +If the new child process was created via +.Xr vfork 2 , +the traced process's stop will also include the +.Dv PL_FLAG_VFORKED +flag. +Note that new child processes will be attached with the default +tracing event mask; +they do not inherit the event mask of the traced process. +.Pp +When this event flag is not enabled, +new child processes will execute without tracing enabled. +.It Dv PTRACE_LWP +This event flag controls tracing of LWP +.Pq kernel thread +creation and destruction. +When this event is enabled, +new LWPs will stop and report an event with +.Dv PL_FLAG_BORN +set before executing their first instruction, +and exiting LWPs will stop and report an event with +.Dv PL_FLAG_EXITED +set before completing their termination. +.Pp +Note that new processes do not report an event for the creation of their +initial thread, +and exiting processes do not report an event for the termination of the +last thread. +.It Dv PTRACE_VFORK +Report a stop event when a parent process resumes after a +.Xr vfork 2 . +.Pp +When a thread in the traced process creates a new child process via +.Xr vfork 2 , +the stop that reports +.Dv PL_FLAG_FORKED +and +.Dv PL_FLAG_SCX +occurs just after the child process is created, +but before the thread waits for the child process to stop sharing process +memory. +If a debugger is not tracing the new child process, +it must ensure that no breakpoints are enabled in the shared process +memory before detaching from the new child process. +This means that no breakpoints are enabled in the parent process either. +.Pp +The +.Dv PTRACE_VFORK +flag enables a new stop that indicates when the new child process stops +sharing the process memory of the parent process. +A debugger can reinsert breakpoints in the parent process and resume it +in response to this event. +This event is indicated by setting the +.Dv PL_FLAG_VFORK_DONE +flag. +.El +.Pp +The default tracing event mask when attaching to a process via +.Dv PT_ATTACH , +.Dv PT_TRACE_ME , +or +.Dv PTRACE_FORK +includes only +.Dv PTRACE_EXEC +events. +All other event flags are disabled. +.Sh PTRACE REQUESTS +.Pp +The +.Fa request +argument specifies what operation is being performed; the meaning of +the rest of the arguments depends on the operation, but except for one +special case noted below, all +.Fn ptrace +calls are made by the tracing process, and the +.Fa pid +argument specifies the process ID of the traced process +or a corresponding thread ID. +The +.Fa request +argument +can be: +.Bl -tag -width "Dv PT_GET_EVENT_MASK" +.It Dv PT_TRACE_ME +This request is the only one used by the traced process; it declares +that the process expects to be traced by its parent. +All the other arguments are ignored. +(If the parent process does not expect to trace the child, it will +probably be rather confused by the results; once the traced process +stops, it cannot be made to continue except via +.Fn ptrace . ) +When a process has used this request and calls +.Xr execve 2 +or any of the routines built on it +(such as +.Xr execv 3 ) , +it will stop before executing the first instruction of the new image. +Also, any setuid or setgid bits on the executable being executed will +be ignored. +If the child was created by +.Xr vfork 2 +system call or +.Xr rfork 2 +call with the +.Dv RFMEM +flag specified, the debugging events are reported to the parent +only after the +.Xr execve 2 +is executed. +.It Dv PT_READ_I , Dv PT_READ_D +These requests read a single +.Vt int +of data from the traced process's address space. +Traditionally, +.Fn ptrace +has allowed for machines with distinct address spaces for instruction +and data, which is why there are two requests: conceptually, +.Dv PT_READ_I +reads from the instruction space and +.Dv PT_READ_D +reads from the data space. +In the current +.Fx +implementation, these two requests are completely identical. +The +.Fa addr +argument specifies the address +(in the traced process's virtual address space) +at which the read is to be done. +This address does not have to meet any alignment constraints. +The value read is returned as the return value from +.Fn ptrace . +.It Dv PT_WRITE_I , Dv PT_WRITE_D +These requests parallel +.Dv PT_READ_I +and +.Dv PT_READ_D , +except that they write rather than read. +The +.Fa data +argument supplies the value to be written. +.It Dv PT_IO +This request allows reading and writing arbitrary amounts of data in +the traced process's address space. +The +.Fa addr +argument specifies a pointer to a +.Vt "struct ptrace_io_desc" , +which is defined as follows: +.Bd -literal +struct ptrace_io_desc { + int piod_op; /* I/O operation */ + void *piod_offs; /* child offset */ + void *piod_addr; /* parent offset */ + size_t piod_len; /* request length */ +}; + +/* + * Operations in piod_op. + */ +#define PIOD_READ_D 1 /* Read from D space */ +#define PIOD_WRITE_D 2 /* Write to D space */ +#define PIOD_READ_I 3 /* Read from I space */ +#define PIOD_WRITE_I 4 /* Write to I space */ +.Ed +.Pp +The +.Fa data +argument is ignored. +The actual number of bytes read or written is stored in +.Va piod_len +upon return. +.It Dv PT_CONTINUE +The traced process continues execution. +The +.Fa addr +argument +is an address specifying the place where execution is to be resumed +(a new value for the program counter), +or +.Po Vt caddr_t Pc Ns 1 +to indicate that execution is to pick up where it left off. +The +.Fa data +argument +provides a signal number to be delivered to the traced process as it +resumes execution, or 0 if no signal is to be sent. +.It Dv PT_STEP +The traced process is single stepped one instruction. +The +.Fa addr +argument +should be passed +.Po Vt caddr_t Pc Ns 1 . +The +.Fa data +argument +provides a signal number to be delivered to the traced process as it +resumes execution, or 0 if no signal is to be sent. +.It Dv PT_KILL +The traced process terminates, as if +.Dv PT_CONTINUE +had been used with +.Dv SIGKILL +given as the signal to be delivered. +.It Dv PT_ATTACH +This request allows a process to gain control of an otherwise +unrelated process and begin tracing it. +It does not need any cooperation from the process to trace. +In +this case, +.Fa pid +specifies the process ID of the process to trace, and the other +two arguments are ignored. +This request requires that the target process must have the same real +UID as the tracing process, and that it must not be executing a setuid +or setgid executable. +(If the tracing process is running as root, these restrictions do not +apply.) +The tracing process will see the newly-traced process stop and may +then control it as if it had been traced all along. +.It Dv PT_DETACH +This request is like PT_CONTINUE, except that it does not allow +specifying an alternate place to continue execution, and after it +succeeds, the traced process is no longer traced and continues +execution normally. +.Pp +The parent of the traced process will be sent a +.Dv SIGCHLD +to indicate that the process has continued from a stopped state regardless of +whether the process was in a stopped state prior to the corresponding +.Dv PT_ATTACH +request. +A +.Xr wait 2 +for the traced process would indicate that it had been continued. +.It Dv PT_GETREGS +This request reads the traced process's machine registers into the +.Do +.Vt "struct reg" +.Dc +(defined in +.In machine/reg.h ) +pointed to by +.Fa addr . +.It Dv PT_SETREGS +This request is the converse of +.Dv PT_GETREGS ; +it loads the traced process's machine registers from the +.Do +.Vt "struct reg" +.Dc +(defined in +.In machine/reg.h ) +pointed to by +.Fa addr . +.It Dv PT_GETFPREGS +This request reads the traced process's floating-point registers into +the +.Do +.Vt "struct fpreg" +.Dc +(defined in +.In machine/reg.h ) +pointed to by +.Fa addr . +.It Dv PT_SETFPREGS +This request is the converse of +.Dv PT_GETFPREGS ; +it loads the traced process's floating-point registers from the +.Do +.Vt "struct fpreg" +.Dc +(defined in +.In machine/reg.h ) +pointed to by +.Fa addr . +.It Dv PT_GETDBREGS +This request reads the traced process's debug registers into +the +.Do +.Vt "struct dbreg" +.Dc +(defined in +.In machine/reg.h ) +pointed to by +.Fa addr . +.It Dv PT_SETDBREGS +This request is the converse of +.Dv PT_GETDBREGS ; +it loads the traced process's debug registers from the +.Do +.Vt "struct dbreg" +.Dc +(defined in +.In machine/reg.h ) +pointed to by +.Fa addr . +.It Dv PT_GETREGSET +This request reads the registers from the traced process. +The +.Fa data +argument specifies the register set to read, with the +.Fa addr +argument pointing at a +.Vt "struct iovec" +where the +.Va iov_base +field points to a register set specific structure to hold the registers, +and the +.Va iov_len +field holds the length of the structure. +.It Dv PT_SETREGSET +This request writes to the registers of the traced process. +The +.Fa data +argument specifies the register set to write to, with the +.Fa addr +argument pointing at a +.Vt "struct iovec" +where the +.Va iov_base +field points to a register set specific structure to hold the registers, +and the +.Va iov_len +field holds the length of the structure. +If +.Va iov_base +is NULL the kernel will return the expected length of the register set +specific structure in the +.Va iov_len +field and not change the target register set. +.It Dv PT_LWPINFO +This request can be used to obtain information about the kernel thread, +also known as light-weight process, that caused the traced process to stop. +The +.Fa addr +argument specifies a pointer to a +.Vt "struct ptrace_lwpinfo" , +which is defined as follows: +.Bd -literal +struct ptrace_lwpinfo { + lwpid_t pl_lwpid; + int pl_event; + int pl_flags; + sigset_t pl_sigmask; + sigset_t pl_siglist; + siginfo_t pl_siginfo; + char pl_tdname[MAXCOMLEN + 1]; + pid_t pl_child_pid; + u_int pl_syscall_code; + u_int pl_syscall_narg; +}; +.Ed +.Pp +The +.Fa data +argument is to be set to the size of the structure known to the caller. +This allows the structure to grow without affecting older programs. +.Pp +The fields in the +.Vt "struct ptrace_lwpinfo" +have the following meaning: +.Bl -tag -width indent -compact +.It Va pl_lwpid +LWP id of the thread +.It Va pl_event +Event that caused the stop. +Currently defined events are: +.Bl -tag -width "Dv PL_EVENT_SIGNAL" -compact +.It Dv PL_EVENT_NONE +No reason given +.It Dv PL_EVENT_SIGNAL +Thread stopped due to the pending signal +.El +.It Va pl_flags +Flags that specify additional details about observed stop. +Currently defined flags are: +.Bl -tag -width indent -compact +.It Dv PL_FLAG_SCE +The thread stopped due to system call entry, right after the kernel is entered. +The debugger may examine syscall arguments that are stored in memory and +registers according to the ABI of the current process, and modify them, +if needed. +.It Dv PL_FLAG_SCX +The thread is stopped immediately before syscall is returning to the usermode. +The debugger may examine system call return values in the ABI-defined registers +and/or memory. +.It Dv PL_FLAG_EXEC +When +.Dv PL_FLAG_SCX +is set, this flag may be additionally specified to inform that the +program being executed by debuggee process has been changed by successful +execution of a system call from the +.Fn execve 2 +family. +.It Dv PL_FLAG_SI +Indicates that +.Va pl_siginfo +member of +.Vt "struct ptrace_lwpinfo" +contains valid information. +.It Dv PL_FLAG_FORKED +Indicates that the process is returning from a call to +.Fn fork 2 +that created a new child process. +The process identifier of the new process is available in the +.Va pl_child_pid +member of +.Vt "struct ptrace_lwpinfo" . +.It Dv PL_FLAG_CHILD +The flag is set for first event reported from a new child which is +automatically attached when +.Dv PTRACE_FORK +is enabled. +.It Dv PL_FLAG_BORN +This flag is set for the first event reported from a new LWP when +.Dv PTRACE_LWP +is enabled. +It is reported along with +.Dv PL_FLAG_SCX . +.It Dv PL_FLAG_EXITED +This flag is set for the last event reported by an exiting LWP when +.Dv PTRACE_LWP +is enabled. +Note that this event is not reported when the last LWP in a process exits. +The termination of the last thread is reported via a normal process exit +event. +.It Dv PL_FLAG_VFORKED +Indicates that the thread is returning from a call to +.Xr vfork 2 +that created a new child process. +This flag is set in addition to +.Dv PL_FLAG_FORKED . +.It Dv PL_FLAG_VFORK_DONE +Indicates that the thread has resumed after a child process created via +.Xr vfork 2 +has stopped sharing its address space with the traced process. +.El +.It Va pl_sigmask +The current signal mask of the LWP +.It Va pl_siglist +The current pending set of signals for the LWP. +Note that signals that are delivered to the process would not appear +on an LWP siglist until the thread is selected for delivery. +.It Va pl_siginfo +The siginfo that accompanies the signal pending. +Only valid for +.Dv PL_EVENT_SIGNAL +stop when +.Dv PL_FLAG_SI +is set in +.Va pl_flags . +.It Va pl_tdname +The name of the thread. +.It Va pl_child_pid +The process identifier of the new child process. +Only valid for a +.Dv PL_EVENT_SIGNAL +stop when +.Dv PL_FLAG_FORKED +is set in +.Va pl_flags . +.It Va pl_syscall_code +The ABI-specific identifier of the current system call. +Note that for indirect system calls this field reports the indirected +system call. +Only valid when +.Dv PL_FLAG_SCE +or +.Dv PL_FLAG_SCX +is set in +.Va pl_flags . +.It Va pl_syscall_narg +The number of arguments passed to the current system call not counting +the system call identifier. +Note that for indirect system calls this field reports the arguments +passed to the indirected system call. +Only valid when +.Dv PL_FLAG_SCE +or +.Dv PL_FLAG_SCX +is set in +.Va pl_flags . +.El +.It Dv PT_GETNUMLWPS +This request returns the number of kernel threads associated with the +traced process. +.It Dv PT_GETLWPLIST +This request can be used to get the current thread list. +A pointer to an array of type +.Vt lwpid_t +should be passed in +.Fa addr , +with the array size specified by +.Fa data . +The return value from +.Fn ptrace +is the count of array entries filled in. +.It Dv PT_SETSTEP +This request will turn on single stepping of the specified process. +Stepping is automatically disabled when a single step trap is caught. +.It Dv PT_CLEARSTEP +This request will turn off single stepping of the specified process. +.It Dv PT_SUSPEND +This request will suspend the specified thread. +.It Dv PT_RESUME +This request will resume the specified thread. +.It Dv PT_TO_SCE +This request will set the +.Dv PTRACE_SCE +event flag to trace all future system call entries and continue the process. +The +.Fa addr +and +.Fa data +arguments are used the same as for +.Dv PT_CONTINUE . +.It Dv PT_TO_SCX +This request will set the +.Dv PTRACE_SCX +event flag to trace all future system call exits and continue the process. +The +.Fa addr +and +.Fa data +arguments are used the same as for +.Dv PT_CONTINUE . +.It Dv PT_SYSCALL +This request will set the +.Dv PTRACE_SYSCALL +event flag to trace all future system call entries and exits and continue +the process. +The +.Fa addr +and +.Fa data +arguments are used the same as for +.Dv PT_CONTINUE . +.It Dv PT_GET_SC_ARGS +For the thread which is stopped in either +.Dv PL_FLAG_SCE +or +.Dv PL_FLAG_SCX +state, that is, on entry or exit to a syscall, +this request fetches the syscall arguments. +.Pp +The arguments are copied out into the buffer pointed to by the +.Fa addr +pointer, sequentially. +Each syscall argument is stored as the machine word. +Kernel copies out as many arguments as the syscall accepts, +see the +.Va pl_syscall_narg +member of the +.Vt struct ptrace_lwpinfo , +but not more than the +.Fa data +bytes in total are copied. +.It Dv PT_GET_SC_RET +Fetch the system call return values on exit from a syscall. +This request is only valid for threads stopped in a syscall +exit (the +.Dv PL_FLAG_SCX +state). +The +.Fa addr +argument specifies a pointer to a +.Vt "struct ptrace_sc_ret" , +which is defined as follows: +.Bd -literal +struct ptrace_sc_ret { + register_t sr_retval[2]; + int sr_error; +}; +.Ed +.Pp +The +.Fa data +argument is set to the size of the structure. +.Pp +If the system call completed successfully, +.Va sr_error +is set to zero and the return values of the system call are saved in +.Va sr_retval . +If the system call failed to execute, +.Va sr_error +field is set to a positive +.Xr errno 2 +value. +If the system call completed in an unusual fashion, +.Va sr_error +is set to a negative value: +.Bl -tag -width EJUSTRETURN -compact +.It Dv ERESTART +System call will be restarted. +.It Dv EJUSTRETURN +System call completed sucessfully but did not set a return value +.Po for example, +.Xr setcontext 2 +and +.Xr sigreturn 2 +.Pc . +.El +.It Dv PT_FOLLOW_FORK +This request controls tracing for new child processes of a traced process. +If +.Fa data +is non-zero, +.Dv PTRACE_FORK +is set in the traced process's event tracing mask. +If +.Fa data +is zero, +.Dv PTRACE_FORK +is cleared from the traced process's event tracing mask. +.It Dv PT_LWP_EVENTS +This request controls tracing of LWP creation and destruction. +If +.Fa data +is non-zero, +.Dv PTRACE_LWP +is set in the traced process's event tracing mask. +If +.Fa data +is zero, +.Dv PTRACE_LWP +is cleared from the traced process's event tracing mask. +.It Dv PT_GET_EVENT_MASK +This request reads the traced process's event tracing mask into the +integer pointed to by +.Fa addr . +The size of the integer must be passed in +.Fa data . +.It Dv PT_SET_EVENT_MASK +This request sets the traced process's event tracing mask from the +integer pointed to by +.Fa addr . +The size of the integer must be passed in +.Fa data . +.It Dv PT_VM_TIMESTAMP +This request returns the generation number or timestamp of the memory map of +the traced process as the return value from +.Fn ptrace . +This provides a low-cost way for the tracing process to determine if the +VM map changed since the last time this request was made. +.It Dv PT_VM_ENTRY +This request is used to iterate over the entries of the VM map of the traced +process. +The +.Fa addr +argument specifies a pointer to a +.Vt "struct ptrace_vm_entry" , +which is defined as follows: +.Bd -literal +struct ptrace_vm_entry { + int pve_entry; + int pve_timestamp; + u_long pve_start; + u_long pve_end; + u_long pve_offset; + u_int pve_prot; + u_int pve_pathlen; + long pve_fileid; + uint32_t pve_fsid; + char *pve_path; +}; +.Ed +.Pp +The first entry is returned by setting +.Va pve_entry +to zero. +Subsequent entries are returned by leaving +.Va pve_entry +unmodified from the value returned by previous requests. +The +.Va pve_timestamp +field can be used to detect changes to the VM map while iterating over the +entries. +The tracing process can then take appropriate action, such as restarting. +By setting +.Va pve_pathlen +to a non-zero value on entry, the pathname of the backing object is returned +in the buffer pointed to by +.Va pve_path , +provided the entry is backed by a vnode. +The +.Va pve_pathlen +field is updated with the actual length of the pathname (including the +terminating null character). +The +.Va pve_offset +field is the offset within the backing object at which the range starts. +The range is located in the VM space at +.Va pve_start +and extends up to +.Va pve_end +(inclusive). +.Pp +The +.Fa data +argument is ignored. +.It Dv PT_COREDUMP +This request creates a coredump for the stopped program. +The +.Fa addr +argument specifies a pointer to a +.Vt "struct ptrace_coredump" , +which is defined as follows: +.Bd -literal +struct ptrace_coredump { + int pc_fd; + uint32_t pc_flags; + off_t pc_limit; +}; +.Ed +The fields of the structure are: +.Bl -tag -width pc_flags +.It Dv pc_fd +File descriptor to write the dump to. +It must refer to a regular file, opened for writing. +.It Dv pc_flags +Flags. +The following flags are defined: +.Bl -tag -width PC_COMPRESS +.It Dv PC_COMPRESS +Request compression of the dump. +.It Dv PC_ALL +Include non-dumpable entries into the dump. +The dumper ignores +.Dv MAP_NOCORE +flag of the process map entry, but device mappings are not dumped even with +.Dv PC_ALL +set. +.El +.It Dv pc_limit +Maximum size of the coredump. +Specify zero for no limit. +.El +.Pp +The size of +.Vt "struct ptrace_coredump" +must be passed in +.Fa data . +.It Dv PT_SC_REMOTE +Request to execute a syscall in the context of the traced process, +in the specified thread. +The +.Fa addr +argument must point to the +.Vt "struct ptrace_sc_remote" , +which describes the requested syscall and its arguments, and receives +the result. +The size of +.Vt "struct ptrace_sc_remote" +must be passed in +.Fa data. +.Bd -literal +struct ptrace_sc_remote { + struct ptrace_sc_ret pscr_ret; + u_int pscr_syscall; + u_int pscr_nargs; + u_long *pscr_args; +}; +.Ed +The +.Dv pscr_syscall +contains the syscall number to execute, the +.Dv pscr_nargs +is the number of supplied arguments, which are supplied in the +.Dv pscr_args +array. +Result of the execution is returned in the +.Dv pscr_ret +member. +Note that the request and its result do not affect the returned value from +the currently executed syscall, if any. +.El +.Sh PT_COREDUMP and PT_SC_REMOTE usage +The process must be stopped before dumping or initiating a remote system call. +A single thread in the target process is temporarily unsuspended +in the kernel to perform the action. +If the +.Nm +call fails before a thread is unsuspended, there is no event to +.Xr waitpid 2 +for. +If a thread was unsuspended, it will stop again before the +.Nm +call returns, and the process must be waited upon using +.Xr waitpid 2 +to consume the new stop event. +Since it is hard to deduce whether a thread was unsuspended before +an error occurred, it is recommended to unconditionally perform +.Xr waitpid 2 +with +.Dv WNOHANG +flag after +.Dv PT_COREDUMP +and +.Dv PT_SC_REMOTE , +and silently accept zero result from it. +.Pp +For +.Dv PT_SC_REMOTE , +the selected thread must be stopped in the safe place, which is +currently defined as a syscall exit, or a return from kernel to +user mode (basically, a signal handler call place). +Kernel returns +.Er EBUSY +status if attempt is made to execute remote syscall at unsafe stop. +.Pp +Note that neither +.Dv kern.trap_enotcap +sysctl setting, nor the corresponding +.Xr procctl 2 +flag +.Dv PROC_TRAPCAP_CTL_ENABLE +are obeyed during the execution of the syscall by +.Dv PT_SC_REMOTE . +In other words, +.Dv SIGTRAP +signal is not sent to a process executing in capability mode, +which violated a mode access restriction. +.Pp +Note that due to the mode of execution for the remote syscall, in +particular, the setting where only one thread is allowed to run, +the syscall might block on resources owned by suspended threads. +This might result in the target process deadlock. +In this situation, the only way out is to kill the target. +.Sh ARM MACHINE-SPECIFIC REQUESTS +.Bl -tag -width "Dv PT_SETVFPREGS" +.It Dv PT_GETVFPREGS +Return the thread's +.Dv VFP +machine state in the buffer pointed to by +.Fa addr . +.Pp +The +.Fa data +argument is ignored. +.It Dv PT_SETVFPREGS +Set the thread's +.Dv VFP +machine state from the buffer pointed to by +.Fa addr . +.Pp +The +.Fa data +argument is ignored. +.El +.Sh x86 MACHINE-SPECIFIC REQUESTS +.Bl -tag -width "Dv PT_GETXSTATE_INFO" +.It Dv PT_GETXMMREGS +Copy the XMM FPU state into the buffer pointed to by the +argument +.Fa addr . +The buffer has the same layout as the 32-bit save buffer for the +machine instruction +.Dv FXSAVE . +.Pp +This request is only valid for i386 programs, both on native 32-bit +systems and on amd64 kernels. +For 64-bit amd64 programs, the XMM state is reported as part of +the FPU state returned by the +.Dv PT_GETFPREGS +request. +.Pp +The +.Fa data +argument is ignored. +.It Dv PT_SETXMMREGS +Load the XMM FPU state for the thread from the buffer pointed to +by the argument +.Fa addr . +The buffer has the same layout as the 32-bit load buffer for the +machine instruction +.Dv FXRSTOR . +.Pp +As with +.Dv PT_GETXMMREGS , +this request is only valid for i386 programs. +.Pp +The +.Fa data +argument is ignored. +.It Dv PT_GETXSTATE_INFO +Report which XSAVE FPU extensions are supported by the CPU +and allowed in userspace programs. +The +.Fa addr +argument must point to a variable of type +.Vt struct ptrace_xstate_info , +which contains the information on the request return. +.Vt struct ptrace_xstate_info +is defined as follows: +.Bd -literal +struct ptrace_xstate_info { + uint64_t xsave_mask; + uint32_t xsave_len; +}; +.Ed +The +.Dv xsave_mask +field is a bitmask of the currently enabled extensions. +The meaning of the bits is defined in the Intel and AMD +processor documentation. +The +.Dv xsave_len +field reports the length of the XSAVE area for storing the hardware +state for currently enabled extensions in the format defined by the x86 +.Dv XSAVE +machine instruction. +.Pp +The +.Fa data +argument value must be equal to the size of the +.Vt struct ptrace_xstate_info . +.It Dv PT_GETXSTATE +Return the content of the XSAVE area for the thread. +The +.Fa addr +argument points to the buffer where the content is copied, and the +.Fa data +argument specifies the size of the buffer. +The kernel copies out as much content as allowed by the buffer size. +The buffer layout is specified by the layout of the save area for the +.Dv XSAVE +machine instruction. +.It Dv PT_SETXSTATE +Load the XSAVE state for the thread from the buffer specified by the +.Fa addr +pointer. +The buffer size is passed in the +.Fa data +argument. +The buffer must be at least as large as the +.Vt struct savefpu +(defined in +.Pa x86/fpu.h ) +to allow the complete x87 FPU and XMM state load. +It must not be larger than the XSAVE state length, as reported by the +.Dv xsave_len +field from the +.Vt struct ptrace_xstate_info +of the +.Dv PT_GETXSTATE_INFO +request. +Layout of the buffer is identical to the layout of the load area for the +.Dv XRSTOR +machine instruction. +.It Dv PT_GETFSBASE +Return the value of the base used when doing segmented +memory addressing using the %fs segment register. +The +.Fa addr +argument points to an +.Vt unsigned long +variable where the base value is stored. +.Pp +The +.Fa data +argument is ignored. +.It Dv PT_GETGSBASE +Like the +.Dv PT_GETFSBASE +request, but returns the base for the %gs segment register. +.It Dv PT_SETFSBASE +Set the base for the %fs segment register to the value pointed to +by the +.Fa addr +argument. +.Fa addr +must point to the +.Vt unsigned long +variable containing the new base. +.Pp +The +.Fa data +argument is ignored. +.It Dv PT_SETGSBASE +Like the +.Dv PT_SETFSBASE +request, but sets the base for the %gs segment register. +.El +.Sh PowerPC MACHINE-SPECIFIC REQUESTS +.Bl -tag -width "Dv PT_SETVRREGS" +.It Dv PT_GETVRREGS +Return the thread's +.Dv ALTIVEC +machine state in the buffer pointed to by +.Fa addr . +.Pp +The +.Fa data +argument is ignored. +.It Dv PT_SETVRREGS +Set the thread's +.Dv ALTIVEC +machine state from the buffer pointed to by +.Fa addr . +.Pp +The +.Fa data +argument is ignored. +.It Dv PT_GETVSRREGS +Return doubleword 1 of the thread's +.Dv VSX +registers VSR0-VSR31 in the buffer pointed to by +.Fa addr . +.Pp +The +.Fa data +argument is ignored. +.It Dv PT_SETVSRREGS +Set doubleword 1 of the thread's +.Dv VSX +registers VSR0-VSR31 from the buffer pointed to by +.Fa addr . +.Pp +The +.Fa data +argument is ignored. +.El +.Pp +Additionally, other machine-specific requests can exist. +.Sh RETURN VALUES +Most requests return 0 on success and \-1 on error. +Some requests can cause +.Fn ptrace +to return +\-1 +as a non-error value, among them are +.Dv PT_READ_I +and +.Dv PT_READ_D , +which return the value read from the process memory on success. +To disambiguate, +.Va errno +can be set to 0 before the call and checked afterwards. +.Pp +The current +.Fn ptrace +implementation always sets +.Va errno +to 0 before calling into the kernel, both for historic reasons and for +consistency with other operating systems. +It is recommended to assign zero to +.Va errno +explicitly for forward compatibility. +.Sh ERRORS +The +.Fn ptrace +system call may fail if: +.Bl -tag -width Er +.It Bq Er ESRCH +.Bl -bullet -compact +.It +No process having the specified process ID exists. +.El +.It Bq Er EINVAL +.Bl -bullet -compact +.It +A process attempted to use +.Dv PT_ATTACH +on itself. +.It +The +.Fa request +argument +was not one of the legal requests. +.It +The signal number +(in +.Fa data ) +to +.Dv PT_CONTINUE +was neither 0 nor a legal signal number. +.It +.Dv PT_GETREGS , +.Dv PT_SETREGS , +.Dv PT_GETFPREGS , +.Dv PT_SETFPREGS , +.Dv PT_GETDBREGS , +or +.Dv PT_SETDBREGS +was attempted on a process with no valid register set. +(This is normally true only of system processes.) +.It +.Dv PT_VM_ENTRY +was given an invalid value for +.Fa pve_entry . +This can also be caused by changes to the VM map of the process. +.It +The size (in +.Fa data ) +provided to +.Dv PT_LWPINFO +was less than or equal to zero, or larger than the +.Vt ptrace_lwpinfo +structure known to the kernel. +.It +The size (in +.Fa data ) +provided to the x86-specific +.Dv PT_GETXSTATE_INFO +request was not equal to the size of the +.Vt struct ptrace_xstate_info . +.It +The size (in +.Fa data ) +provided to the x86-specific +.Dv PT_SETXSTATE +request was less than the size of the x87 plus the XMM save area. +.It +The size (in +.Fa data ) +provided to the x86-specific +.Dv PT_SETXSTATE +request was larger than returned in the +.Dv xsave_len +member of the +.Vt struct ptrace_xstate_info +from the +.Dv PT_GETXSTATE_INFO +request. +.It +The base value, provided to the amd64-specific requests +.Dv PT_SETFSBASE +or +.Dv PT_SETGSBASE , +pointed outside of the valid user address space. +This error will not occur in 32-bit programs. +.El +.It Bq Er EBUSY +.Bl -bullet -compact +.It +.Dv PT_ATTACH +was attempted on a process that was already being traced. +.It +A request attempted to manipulate a process that was being traced by +some process other than the one making the request. +.It +A request +(other than +.Dv PT_ATTACH ) +specified a process that was not stopped. +.El +.It Bq Er EPERM +.Bl -bullet -compact +.It +A request +(other than +.Dv PT_ATTACH ) +attempted to manipulate a process that was not being traced at all. +.It +An attempt was made to use +.Dv PT_ATTACH +on a process in violation of the requirements listed under +.Dv PT_ATTACH +above. +.El +.It Bq Er ENOENT +.Bl -bullet -compact +.It +.Dv PT_VM_ENTRY +previously returned the last entry of the memory map. +No more entries exist. +.El +.It Bq Er ENOMEM +.Bl -bullet -compact +.It +A +.Dv PT_READ_I, +.Dv PT_READ_D, +.Dv PT_WRITE_I, or +.Dv PT_WRITE_D +request attempted to access an invalid address, or a memory allocation failure +occurred when accessing process memory. +.El +.It Bq Er ENAMETOOLONG +.Bl -bullet -compact +.It +.Dv PT_VM_ENTRY +cannot return the pathname of the backing object because the buffer is not big +enough. +.Fa pve_pathlen +holds the minimum buffer size required on return. +.El +.El +.Sh SEE ALSO +.Xr execve 2 , +.Xr sigaction 2 , +.Xr wait 2 , +.Xr execv 3 , +.Xr i386_clr_watch 3 , +.Xr i386_set_watch 3 +.Sh HISTORY +The +.Fn ptrace +function appeared in +.At v6 . diff --git a/lib/libsys/ptrace.c b/lib/libsys/ptrace.c new file mode 100644 index 000000000000..65f2ee80d8ea --- /dev/null +++ b/lib/libsys/ptrace.c @@ -0,0 +1,45 @@ +/* + * Copyright (c) 2016 The FreeBSD Foundation. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * 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(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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. + */ + +#include <sys/types.h> +#include <sys/ptrace.h> +#include <errno.h> +#include "libc_private.h" + +__weak_reference(_ptrace, ptrace); + +int +_ptrace(int request, pid_t pid, caddr_t addr, int data) +{ + + errno = 0; + return (__sys_ptrace(request, pid, addr, data)); +} diff --git a/lib/libsys/quotactl.2 b/lib/libsys/quotactl.2 new file mode 100644 index 000000000000..4169d5ade4f6 --- /dev/null +++ b/lib/libsys/quotactl.2 @@ -0,0 +1,260 @@ +.\" Copyright (c) 1983, 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Robert Elz at The University of Melbourne. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd March 30, 2020 +.Dt QUOTACTL 2 +.Os +.Sh NAME +.Nm quotactl +.Nd manipulate file system quotas +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In ufs/ufs/quota.h +.Ft int +.Fn quotactl "const char *path" "int cmd" "int id" "void *addr" +.Sh DESCRIPTION +The +.Fn quotactl +system call enables, disables and +manipulates file system quotas. +A quota control command +given by +.Fa cmd +operates on the given filename +.Fa path +for the given user or group +.Fa id . +(NOTE: One should use the QCMD macro defined in +.In ufs/ufs/quota.h +to formulate the value for +.Fa cmd . ) +The address of an optional command specific data structure, +.Fa addr , +may be given; its interpretation +is discussed below with each command. +.Pp +For commands that use the +.Fa id +identifier, it must be either -1 or any positive value. +The value of -1 indicates that the current UID or GID should be used. +Any other negative value will return an error. +.Pp +Currently quotas are supported only for the +.Dq ufs +file system. +For +.Dq ufs , +a command is composed of a primary command (see below) +and a command type used to interpret the +.Fa id . +Types are supported for interpretation of user identifiers (USRQUOTA) +and group identifiers (GRPQUOTA). +The +.Dq ufs +specific commands are: +.Bl -tag -width Q_GETQUOTASIZEx +.It Dv Q_QUOTAON +Enable disk quotas for the file system specified by +.Fa path . +The command type specifies the type of the quotas being enabled. +The +.Fa addr +argument specifies a file from which to take the quotas. +The quota file must exist; +it is normally created with the +.Xr quotacheck 8 +program. +The +.Fa id +argument is unused. +Only the super-user may turn quotas on. +.It Dv Q_QUOTAOFF +Disable disk quotas for the file system specified by +.Fa path . +The command type specifies the type of the quotas being disabled. +The +.Fa addr +and +.Fa id +arguments are unused. +Only the super-user may turn quotas off. +.It Dv Q_GETQUOTASIZE +Get the wordsize used to represent the quotas for the user or group +(as determined by the command type). +Possible values are 32 for the old-style quota file +and 64 for the new-style quota file. +The +.Fa addr +argument is a pointer to an integer into which the size is stored. +The identifier +.Fa id +is not used. +.It Dv Q_GETQUOTA +Get disk quota limits and current usage for the user or group +(as determined by the command type) with identifier +.Fa id . +The +.Fa addr +argument +is a pointer to a +.Fa struct dqblk +structure (defined in +.In ufs/ufs/quota.h ) . +.It Dv Q_SETQUOTA +Set disk quota limits for the user or group +(as determined by the command type) with identifier +.Fa id . +The +.Fa addr +argument +is a pointer to a +.Fa struct dqblk +structure (defined in +.In ufs/ufs/quota.h ) . +The usage fields of the +.Fa dqblk +structure are ignored. +This system call is restricted to the super-user. +.It Dv Q_SETUSE +Set disk usage limits for the user or group +(as determined by the command type) with identifier +.Fa id . +The +.Fa addr +argument +is a pointer to a +.Fa struct dqblk +structure (defined in +.In ufs/ufs/quota.h ) . +Only the usage fields are used. +This system call is restricted to the super-user. +.It Dv Q_SYNC +Update the on-disk copy of quota usages. +The command type specifies which type of quotas are to be updated. +The +.Fa id +and +.Fa addr +arguments are ignored. +.El +.Sh RETURN VALUES +.Rv -std quotactl +.Sh ERRORS +The +.Fn quotactl +system call will fail if: +.Bl -tag -width Er +.It Bq Er EOPNOTSUPP +The kernel has not been compiled with the +.Dv QUOTA +option. +.It Bq Er EUSERS +The quota table cannot be expanded. +.It Bq Er EINVAL +The +.Fa cmd +argument +or the command type is invalid. +In +.Dv Q_GETQUOTASIZE , +.Dv Q_GETQUOTA , +.Dv Q_SETQUOTA , +and +.Dv Q_SETUSE , +quotas are not currently enabled for this file system. +.Pp +The +.Fa id +argument to +.Dv Q_GETQUOTA , +.Dv Q_SETQUOTA +or +.Dv Q_SETUSE +is a negative value. +.It Bq Er EACCES +In +.Dv Q_QUOTAON , +the quota file is not a plain file. +.It Bq Er EACCES +Search permission is denied for a component of a path prefix. +.It Bq Er ENOTDIR +A component of a path prefix was not a directory. +.It Bq Er ENAMETOOLONG +A component of either pathname exceeded 255 characters, +or the entire length of either path name exceeded 1023 characters. +.It Bq Er ENOENT +A filename does not exist. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating a pathname. +.It Bq Er EROFS +In +.Dv Q_QUOTAON , +either the file system on which quotas are to be enabled is mounted read-only +or the quota file resides on a read-only file system. +.It Bq Er EIO +An +.Tn I/O +error occurred while reading from or writing +to a file containing quotas. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.It Bq Er EFAULT +An invalid +.Fa addr +was supplied; the associated structure could not be copied in or out +of the kernel. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.It Bq Er EPERM +The call was privileged and the caller was not the super-user. +.El +.Sh SEE ALSO +.Xr quota 1 , +.Xr fstab 5 , +.Xr edquota 8 , +.Xr quotacheck 8 , +.Xr quotaon 8 , +.Xr repquota 8 +.Sh HISTORY +The +.Fn quotactl +system call appeared in +.Bx 4.3 Reno . +.Sh BUGS +There should be some way to integrate this call with the resource +limit interface provided by +.Xr setrlimit 2 +and +.Xr getrlimit 2 . diff --git a/lib/libsys/rctl_add_rule.2 b/lib/libsys/rctl_add_rule.2 new file mode 100644 index 000000000000..865c73a48a75 --- /dev/null +++ b/lib/libsys/rctl_add_rule.2 @@ -0,0 +1,218 @@ +.\" Copyright (c) 2016 Eric Badger +.\" All rights reserved. +.\" +.\" 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. +.\" +.Dd September 14, 2016 +.Dt RCTL_ADD_RULE 2 +.Os +.Sh NAME +.Nm rctl_add_rule , +.Nm rctl_get_limits , +.Nm rctl_get_racct , +.Nm rctl_get_rules , +.Nm rctl_remove_rule +.Nd manipulate and query the resource limits database +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/rctl.h +.Ft int +.Fo rctl_add_rule +.Fa "const char *inbufp" "size_t inbuflen" "char *outbufp" "size_t outbuflen" +.Fc +.Ft int +.Fo rctl_get_limits +.Fa "const char *inbufp" "size_t inbuflen" "char *outbufp" "size_t outbuflen" +.Fc +.Ft int +.Fo rctl_get_racct +.Fa "const char *inbufp" "size_t inbuflen" "char *outbufp" "size_t outbuflen" +.Fc +.Ft int +.Fo rctl_get_rules +.Fa "const char *inbufp" "size_t inbuflen" "char *outbufp" "size_t outbuflen" +.Fc +.Ft int +.Fo rctl_remove_rule +.Fa "const char *inbufp" "size_t inbuflen" "char *outbufp" "size_t outbuflen" +.Fc +.Sh DESCRIPTION +These system calls are used to manipulate and query the resource limits +database. +For all functions, +.Fa inbuflen +refers to the length of the buffer pointed to by +.Fa inbufp +and +.Fa outbuflen +refers to the length of the buffer pointed to by +.Fa outbufp . +.Pp +The +.Fn rctl_add_rule +function adds the rule pointed to by +.Fa inbufp +to the resource limits database. +The +.Fa outbufp +and +.Fa outbuflen +arguments are unused. +Rule format is as described in +.Xr rctl 8 , +with exceptions noted in the +.Sx RULES AND FILTERS +section. +.Pp +The +.Fn rctl_get_limits +function returns in +.Fa outbufp +a comma-separated list of rules that apply to the process that +matches the filter specified in +.Fa inbufp . +This includes rules with a subject of the process itself as well as rules +with a different subject (such as user or loginclass) that apply to the +process. +.Pp +The +.Fn rctl_get_racct +function returns resource usage information for a given subject. +The subject is specified by passing a filter in +.Fa inbufp . +Filter syntax is as described in +.Xr rctl 8 , +with exceptions noted in the +.Sx RULES AND FILTERS +section. +A comma-separated list of resources and the amount used of each by the +specified subject is returned in +.Fa outbufp . +The resource and amount is formatted as +.Qq resource=amount . +.Pp +The +.Fn rctl_get_rules +function returns in +.Fa outbufp +a comma-separated list of rules from the resource limits database that +match the filter passed in +.Fa inbufp . +Filter syntax is as described in +.Xr rctl 8 , +with exceptions noted in the +.Sx RULES AND FILTERS +section. +A filter of +.Va :: +may be passed to return all rules. +.Pp +The +.Fn rctl_remove_rule +function removes all rules matching the filter passed in +.Fa inbufp +from the resource limits database. +Filter syntax is as described in +.Xr rctl 8 , +with exceptions noted in the +.Sx RULES AND FILTERS +section. +.Fa outbufp +and +.Fa outbuflen +are unused. +.Sh RULES AND FILTERS +This section explains how the rule and filter format described in +.Xr rctl 8 +differs from the format passed to the system calls themselves. +The rctl tool provides several conveniences that the system calls do not. +When using the system call: +.Bl -dash -offset indent +.It +The subject must be fully specified. +For example, abbreviating +.Ql user +to +.Ql u +is not acceptable. +.It +User and group IDs must be numeric. +For example, +.Ql root +must be expressed as +.Ql 0 . +.It +Units are not permitted on resource amounts. +For example, a quantity of 1024 bytes must be expressed as +.Ql 1024 +and not +.Ql 1k . +.El +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The rctl system calls may fail if: +.Bl -tag -width Er +.It Bq Er ENOSYS +RACCT/RCTL support is not present in the kernel or the +.Va kern.racct.enable +sysctl is 0. +.It Bq Er EINVAL +The rule or filter passed in +.Fa inbufp +is invalid. +.It Bq Er EPERM +User has insufficient privileges to carry out the requested operation. +.It Bq Er E2BIG +.Fa inbufp +or +.Fa outbufp +are too large. +.It Bq Er ESRCH +No process matched the provided rule or filter. +.It Bq Er ENAMETOOLONG +The loginclass or jail name specified is too long. +.It Bq Er ERANGE +The rule amount is outside of the allowable range or +.Fa outbufp +is too small. +.It Bq Er EOPNOTSUPP +The requested operation is not supported for the given rule or filter. +.It Bq Er EFAULT +.Fa inbufp +or +.Fa outbufp +refer to invalid addresses. +.El +.Sh SEE ALSO +.Xr rctl 8 +.Sh HISTORY +The rctl family of system calls appeared in +.Fx 9.0 . +.Sh AUTHORS +.An -nosplit +The rctl system calls were developed by +.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org +under sponsorship from the FreeBSD Foundation. +This manual page was written by +.An Eric Badger Aq Mt badger@FreeBSD.org . diff --git a/lib/libsys/read.2 b/lib/libsys/read.2 new file mode 100644 index 000000000000..4c0f3f5b3f1c --- /dev/null +++ b/lib/libsys/read.2 @@ -0,0 +1,319 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd March 1, 2024 +.Dt READ 2 +.Os +.Sh NAME +.Nm read , +.Nm readv , +.Nm pread , +.Nm preadv +.Nd read input +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft ssize_t +.Fn read "int fd" "void *buf" "size_t nbytes" +.Ft ssize_t +.Fn pread "int fd" "void *buf" "size_t nbytes" "off_t offset" +.In sys/uio.h +.Ft ssize_t +.Fn readv "int fd" "const struct iovec *iov" "int iovcnt" +.Ft ssize_t +.Fn preadv "int fd" "const struct iovec *iov" "int iovcnt" "off_t offset" +.Sh DESCRIPTION +The +.Fn read +system call +attempts to read +.Fa nbytes +of data from the object referenced by the descriptor +.Fa fd +into the buffer pointed to by +.Fa buf . +The +.Fn readv +system call +performs the same action, but scatters the input data +into the +.Fa iovcnt +buffers specified by the members of the +.Fa iov +array: iov[0], iov[1], ..., iov[iovcnt\|\-\|1]. +The +.Fn pread +and +.Fn preadv +system calls +perform the same functions, but read from the specified position in +the file without modifying the file pointer. +.Pp +For +.Fn readv +and +.Fn preadv , +the +.Fa iovec +structure is defined as: +.Pp +.Bd -literal -offset indent -compact +struct iovec { + void *iov_base; /* Base address. */ + size_t iov_len; /* Length. */ +}; +.Ed +.Pp +Each +.Fa iovec +entry specifies the base address and length of an area +in memory where data should be placed. +The +.Fn readv +system call +will always fill an area completely before proceeding +to the next. +.Pp +On objects capable of seeking, the +.Fn read +starts at a position +given by the pointer associated with +.Fa fd +(see +.Xr lseek 2 ) . +Upon return from +.Fn read , +the pointer is incremented by the number of bytes actually read. +.Pp +Objects that are not capable of seeking always read from the current +position. +The value of the pointer associated with such an +object is undefined. +.Pp +Upon successful completion, +.Fn read , +.Fn readv , +.Fn pread +and +.Fn preadv +return the number of bytes actually read and placed in the buffer. +The system guarantees to read the number of bytes requested if +the descriptor references a normal file that has that many bytes left +before the end-of-file, but in no other case. +.Pp +In accordance with +.St -p1003.1-2004 , +both +.Fn read +and +.Fn write +syscalls are atomic with respect to each other in the effects on file +content, when they operate on regular files. +If two threads each call one of the +.Fn read +or +.Fn write , +syscalls, each call will see either all of the changes of the other call, +or none of them. +The +.Fx +kernel implements this guarantee by locking the file ranges affected by +the calls. +.Sh RETURN VALUES +If successful, the +number of bytes actually read is returned. +Upon reading end-of-file, +zero is returned. +Otherwise, a -1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn read , +.Fn readv , +.Fn pread +and +.Fn preadv +system calls +will succeed unless: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument +is not a valid file or socket descriptor open for reading. +.It Bq Er ECONNRESET +The +.Fa fd +argument refers to a socket, and the remote socket end is +forcibly closed. +.It Bq Er EFAULT +The +.Fa buf +argument +points outside the allocated address space. +.It Bq Er EIO +An I/O error occurred while reading from the file system. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.It Bq Er EBUSY +Failed to read from a file, e.g. /proc/<pid>/regs while <pid> is not stopped +.It Bq Er EINTR +A read from a slow device +(i.e.\& one that might block for an arbitrary amount of time) +was interrupted by the delivery of a signal +before any data arrived. +.It Bq Er EINVAL +The pointer associated with +.Fa fd +was negative. +.It Bq Er EAGAIN +The file was marked for non-blocking I/O, +and no data were ready to be read. +.It Bq Er EISDIR +The file descriptor is associated with a directory. +Directories may only be read directly by root if the filesystem supports it and +the +.Dv security.bsd.allow_read_dir +sysctl MIB is set to a non-zero value. +For most scenarios, the +.Xr readdir 3 +function should be used instead. +.It Bq Er EOPNOTSUPP +The file descriptor is associated with a file system and file type that +do not allow regular read operations on it. +.It Bq Er EOVERFLOW +The file descriptor is associated with a regular file, +.Fa nbytes +is greater than 0, +.Fa offset +is before the end-of-file, and +.Fa offset +is greater than or equal to the offset maximum established +for this file system. +.It Bq Er EINVAL +The value +.Fa nbytes +is greater than +.Dv SSIZE_MAX +(or greater than +.Dv INT_MAX , +if the sysctl +.Va debug.iosize_max_clamp +is non-zero). +.El +.Pp +In addition, +.Fn readv +and +.Fn preadv +may return one of the following errors: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa iovcnt +argument +was less than or equal to 0, or greater than +.Dv IOV_MAX . +.It Bq Er EINVAL +One of the +.Fa iov_len +values in the +.Fa iov +array was negative. +.It Bq Er EINVAL +The sum of the +.Fa iov_len +values in the +.Fa iov +array is greater than +.Dv SSIZE_MAX +(or greater than +.Dv INT_MAX , +if the sysctl +.Va debug.iosize_max_clamp +is non-zero). +.It Bq Er EFAULT +Part of the +.Fa iov +array points outside the process's allocated address space. +.El +.Pp +The +.Fn pread +and +.Fn preadv +system calls may also return the following errors: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa offset +value was negative. +.It Bq Er ESPIPE +The file descriptor is associated with a pipe, socket, or FIFO. +.El +.Sh SEE ALSO +.Xr dup 2 , +.Xr fcntl 2 , +.Xr getdirentries 2 , +.Xr open 2 , +.Xr pipe 2 , +.Xr select 2 , +.Xr socket 2 , +.Xr socketpair 2 , +.Xr write 2 , +.Xr fread 3 , +.Xr readdir 3 +.Sh STANDARDS +The +.Fn read +system call is expected to conform to +.St -p1003.1-90 . +The +.Fn readv +and +.Fn pread +system calls are expected to conform to +.St -xpg4.2 . +.Sh HISTORY +The +.Fn preadv +system call appeared in +.Fx 6.0 . +The +.Fn pread +function appeared in +.At V.4 . +The +.Fn readv +system call appeared in +.Bx 4.2 . +The +.Fn read +function appeared in +.At v1 . diff --git a/lib/libsys/readlink.2 b/lib/libsys/readlink.2 new file mode 100644 index 000000000000..9c3476697388 --- /dev/null +++ b/lib/libsys/readlink.2 @@ -0,0 +1,158 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd March 30, 2020 +.Dt READLINK 2 +.Os +.Sh NAME +.Nm readlink , +.Nm readlinkat +.Nd read value of a symbolic link +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft ssize_t +.Fn readlink "const char *restrict path" "char *restrict buf" "size_t bufsiz" +.Ft ssize_t +.Fo readlinkat +.Fa "int fd" "const char *restrict path" "char *restrict buf" "size_t bufsize" +.Fc +.Sh DESCRIPTION +The +.Fn readlink +system call +places the contents of the symbolic link +.Fa path +in the buffer +.Fa buf , +which has size +.Fa bufsiz . +The +.Fn readlink +system call does not append a +.Dv NUL +character to +.Fa buf . +.Pp +The +.Fn readlinkat +system call is equivalent to +.Fn readlink +except in the case where +.Fa path +specifies a relative path. +In this case the symbolic link whose content is read relative to the +directory associated with the file descriptor +.Fa fd +instead of the current working directory. +If +.Fn readlinkat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is +identical to a call to +.Fn readlink . +.Sh RETURN VALUES +The call returns the count of characters placed in the buffer +if it succeeds, or a \-1 if an error occurs, placing the error +code in the global variable +.Va errno . +.Sh ERRORS +The +.Fn readlink +system call +will fail if: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named file does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EINVAL +The named file is not a symbolic link. +.It Bq Er EIO +An I/O error occurred while reading from the file system. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.It Bq Er EFAULT +The +.Fa buf +argument +extends outside the process's allocated address space. +.El +.Pp +In addition to the errors returned by the +.Fn readlink , +the +.Fn readlinkat +may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El +.Sh SEE ALSO +.Xr fhreadlink 2 , +.Xr lstat 2 , +.Xr stat 2 , +.Xr symlink 2 , +.Xr symlink 7 +.Sh STANDARDS +The +.Fn readlinkat +system call follows The Open Group Extended API Set 2 specification. +.Sh HISTORY +The +.Fn readlink +system call appeared in +.Bx 4.2 . +The +.Fn readlinkat +system call appeared in +.Fx 8.0 . diff --git a/lib/libsys/reboot.2 b/lib/libsys/reboot.2 new file mode 100644 index 000000000000..f6c7bf6c83cc --- /dev/null +++ b/lib/libsys/reboot.2 @@ -0,0 +1,162 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd July 10, 2018 +.Dt REBOOT 2 +.Os +.Sh NAME +.Nm reboot +.Nd reboot system or halt processor +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.In sys/reboot.h +.Ft int +.Fn reboot "int howto" +.Sh DESCRIPTION +The +.Fn reboot +system call +reboots the system. +Only the super-user may reboot a machine on demand. +However, a reboot is invoked +automatically in the event of unrecoverable system failures. +.Pp +The +.Fa howto +argument +is a mask of options; the system call interface allows the following +options, defined in the include file +.In sys/reboot.h , +to be passed +to the new kernel or the new bootstrap and init programs. +.Bl -tag -width RB_POWERCYCLE +.It Dv RB_AUTOBOOT +The default, causing the system to reboot in its usual fashion. +.It Dv RB_ASKNAME +Normally the system only prompts the user if the loader specified root +file system has an error. +This flag forces it to always prompt the user for the root partition. +.It Dv RB_DFLTROOT +Use the compiled in root device. +Normally, the system uses the device from which it was booted +as the root device if possible. +(The default behavior is dependent on the ability of the bootstrap program +to determine the drive from which it was loaded, which is not possible +on all systems.) +.It Dv RB_DUMP +Dump kernel memory before rebooting; see +.Xr savecore 8 +for more information. +.It Dv RB_HALT +The processor is simply halted; no reboot takes place. +This option should be used with caution. +.It Dv RB_POWERCYCLE +After halting, the shutdown code will do what it can to turn +off the power and then turn the power back on. +This requires hardware support, usually an auxiliary microprocessor +that can sequence the power supply. +At present only the +.Xr ipmi 4 +driver implements this feature. +.It Dv RB_POWEROFF +After halting, the shutdown code will do what it can to turn +off the power. +This requires hardware support. +.It Dv RB_KDB +Load the symbol table and enable a built-in debugger in the system. +This option will have no useful function if the kernel is not configured +for debugging. +Several other options have different meaning if combined +with this option, although their use may not be possible +via the +.Fn reboot +system call. +See +.Xr ddb 4 +for more information. +.It Dv RB_NOSYNC +Normally, the disks are sync'd (see +.Xr sync 8 ) +before the processor is halted or rebooted. +This option may be useful if file system changes have been made manually +or if the processor is on fire. +.It Dv RB_REROOT +Instead of rebooting, unmount all filesystems except the one containing +currently-running executable, and mount root filesystem using the same +mechanism which is used during normal boot, based on +vfs.root.mountfrom +.Xr kenv 1 +variable. +.It Dv RB_RDONLY +Initially mount the root file system read-only. +This is currently the default, and this option has been deprecated. +.It Dv RB_SINGLE +Normally, the reboot procedure involves an automatic disk consistency +check and then multi-user operations. +.Dv RB_SINGLE +prevents this, booting the system with a single-user shell +on the console. +.Dv RB_SINGLE +is actually interpreted by the +.Xr init 8 +program in the newly booted system. +.El +.Pp +When no options are given (i.e., +.Dv RB_AUTOBOOT +is used), the system is +rebooted from file +.Dq kernel +in the root file system of unit 0 +of a disk chosen in a processor specific way. +An automatic consistency check of the disks is normally performed +(see +.Xr fsck 8 ) . +.Sh RETURN VALUES +If successful, this call never returns. +Otherwise, a -1 is returned and an error is returned in the global +variable +.Va errno . +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EPERM +The caller is not the super-user. +.El +.Sh SEE ALSO +.Xr crash 8 , +.Xr halt 8 , +.Xr init 8 , +.Xr reboot 8 , +.Xr savecore 8 , +.Xr reboot 9 +.Sh HISTORY +The +.Fn reboot +system call appeared in +.Bx 4.0 . diff --git a/lib/libsys/recv.2 b/lib/libsys/recv.2 new file mode 100644 index 000000000000..b78cd70b8a1d --- /dev/null +++ b/lib/libsys/recv.2 @@ -0,0 +1,402 @@ +.\" Copyright (c) 1983, 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd May 17, 2025 +.Dt RECV 2 +.Os +.Sh NAME +.Nm recv , +.Nm recvfrom , +.Nm recvmsg , +.Nm recvmmsg +.Nd receive message(s) from a socket +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/socket.h +.Ft ssize_t +.Fn recv "int s" "void *buf" "size_t len" "int flags" +.Ft ssize_t +.Fn recvfrom "int s" "void *buf" "size_t len" "int flags" "struct sockaddr * restrict from" "socklen_t * restrict fromlen" +.Ft ssize_t +.Fn recvmsg "int s" "struct msghdr *msg" "int flags" +.Ft ssize_t +.Fn recvmmsg "int s" "struct mmsghdr * restrict msgvec" "size_t vlen" "int flags" "const struct timespec * restrict timeout" +.Sh DESCRIPTION +The +.Fn recvfrom , +.Fn recvmsg , +and +.Fn recvmmsg +system calls +are used to receive messages from a socket, +and may be used to receive data on a socket whether or not +it is connection-oriented. +.Pp +If +.Fa from +is not a null pointer +and the socket is not connection-oriented, +the source address of the message is filled in. +The +.Fa fromlen +argument +is a value-result argument, initialized to the size of +the buffer associated with +.Fa from , +and modified on return to indicate the actual size of the +address stored there. +.Pp +The +.Fn recv +function is normally used only on a +.Em connected +socket (see +.Xr connect 2 ) +and is identical to +.Fn recvfrom +with a +null pointer passed as its +.Fa from +argument. +.Pp +The +.Fn recvmmsg +function is used to receive multiple +messages at a call. +Their number is supplied by +.Fa vlen . +The messages are placed in the buffers described by +.Fa msgvec +vector, after reception. +The size of each received message is placed in the +.Fa msg_len +field of each element of the vector. +If +.Fa timeout +is NULL the call blocks until the data is available for each +supplied message buffer. +Otherwise it waits for data for the specified amount of time. +If the timeout expired and there is no data received, +a value 0 is returned. +The +.Xr ppoll 2 +system call is used to implement the timeout mechanism, +before first receive is performed. +.Pp +The +.Fn recv , +.Fn recvfrom +and +.Fn recvmsg +return the length of the message on successful +completion, whereas +.Fn recvmmsg +returns the number of received messages. +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 (see +.Xr socket 2 ) . +.Pp +If no messages are available at the socket, the +receive call waits for a message to arrive, unless +the socket is non-blocking (see +.Xr fcntl 2 ) +in which case the value +\-1 is returned and the global variable +.Va errno +is set to +.Er EAGAIN . +The receive calls except +.Fn recvmmsg +normally return any data available, +up to the requested amount, +rather than waiting for receipt of the full amount requested; +this behavior is affected by the socket-level options +.Dv SO_RCVLOWAT +and +.Dv SO_RCVTIMEO +described in +.Xr getsockopt 2 . +The +.Fn recvmmsg +function implements this behaviour for each message in the vector. +.Pp +The +.Xr select 2 +system call may be used to determine when more data arrives. +.Pp +The +.Fa flags +argument to a +.Fn recv +function is formed by +.Em or Ap ing +one or more of the values: +.Bl -column ".Dv MSG_CMSG_CLOEXEC" -offset indent +.It Dv MSG_OOB Ta process out-of-band data +.It Dv MSG_PEEK Ta peek at incoming message +.It Dv MSG_TRUNC Ta return real packet or datagram length +.It Dv MSG_WAITALL Ta wait for full request or error +.It Dv MSG_DONTWAIT Ta do not block +.It Dv MSG_CMSG_CLOEXEC Ta set received fds close-on-exec +.It Dv MSG_CMSG_CLOFORK Ta set received fds close-on-fork +.It Dv MSG_WAITFORONE Ta do not block after receiving the first message +(only for +.Fn recvmmsg +) +.El +.Pp +The +.Dv MSG_OOB +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. +The +.Dv MSG_PEEK +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. +The +.Dv MSG_TRUNC +flag causes the receive operation to return the full length of the packet +or datagram even if larger than provided buffer. The flag is supported +on SOCK_DGRAM sockets for +.Dv AF_INET +, +.Dv AF_INET6 +and +.Dv AF_UNIX +families. +The +.Dv MSG_WAITALL +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. +The +.Dv MSG_DONTWAIT +flag requests the call to return when it would block otherwise. +If no data is available, +.Va errno +is set to +.Er EAGAIN . +This flag is not available in +.St -ansiC +or +.St -isoC-99 +compilation mode. +The +.Dv MSG_WAITFORONE +flag sets MSG_DONTWAIT after the first message has been received. +This flag is only relevant for +.Fn recvmmsg . +.Pp +The +.Fn recvmsg +system call uses a +.Fa msghdr +structure to minimize the number of directly supplied arguments. +This structure has the following form, as defined in +.In sys/socket.h : +.Bd -literal +struct msghdr { + void *msg_name; /* optional address */ + socklen_t msg_namelen; /* size of address */ + struct iovec *msg_iov; /* scatter/gather array */ + int msg_iovlen; /* # elements in msg_iov */ + void *msg_control; /* ancillary data, see below */ + socklen_t msg_controllen;/* ancillary data buffer len */ + int msg_flags; /* flags on received message */ +}; +.Ed +.Pp +Here +.Fa msg_name +and +.Fa msg_namelen +specify the source address if the socket is unconnected; +.Fa msg_name +may be given as a null pointer if no names are desired or required. +The +.Fa msg_iov +and +.Fa msg_iovlen +arguments +describe scatter gather locations, as discussed in +.Xr read 2 . +The +.Fa msg_control +argument, +which has length +.Fa msg_controllen , +points to a buffer for other protocol control related messages +or other miscellaneous ancillary data. +The messages are of the form: +.Bd -literal +struct cmsghdr { + socklen_t cmsg_len; /* data byte count, including hdr */ + int cmsg_level; /* originating protocol */ + int cmsg_type; /* protocol-specific type */ +/* followed by + u_char cmsg_data[]; */ +}; +.Ed +.Pp +As an example, the SO_TIMESTAMP socket option returns a reception +timestamp for UDP packets. +.Pp +With +.Dv AF_UNIX +domain sockets, ancillary data can be used to pass file descriptors and +process credentials. +See +.Xr unix 4 +for details. +.Pp +The +.Fa msg_flags +field is set on return according to the message received. +.Dv MSG_EOR +indicates end-of-record; +the data returned completed a record (generally used with sockets of type +.Dv SOCK_SEQPACKET ) . +.Dv MSG_TRUNC +indicates that +the trailing portion of a datagram was discarded because the datagram +was larger than the buffer supplied. +.Dv MSG_CTRUNC +indicates that some +control data were discarded due to lack of space in the buffer +for ancillary data. +.Dv MSG_OOB +is returned to indicate that expedited or out-of-band data were received. +.Pp +The +.Fn recvmmsg +system call uses the +.Fa mmsghdr +structure, defined as follows in the +.In sys/socket.h +header: +.Bd -literal +struct mmsghdr { + struct msghdr msg_hdr; /* message header */ + ssize_t msg_len; /* message length */ +}; +.Ed +.Pp +On data reception the +.Fa msg_len +field is updated to the length of the received message. +.Sh RETURN VALUES +On successful completion, the +.Fn recv , +.Fn recvfrom , +and +.Fn recvmsg +functions return the number of bytes received, while the +.Fn recvmmsg +function returns the number of messages received. +If no messages are available to be received and the peer has +performed an orderly shutdown, 0 is returned. +Otherwise, -1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +The calls fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The argument +.Fa s +is an invalid descriptor. +.It Bq Er ECONNRESET +The remote socket end is forcibly closed. +.It Bq Er ENOTCONN +The socket is associated with a connection-oriented protocol +and has not been connected (see +.Xr connect 2 +and +.Xr accept 2 ) . +.It Bq Er ENOTSOCK +The argument +.Fa s +does not refer to a socket. +.It Bq Er EMFILE +The +.Fn recvmsg +system call +was used to receive rights (file descriptors) that were in flight on the +connection. +However, the receiving program did not have enough free file +descriptor slots to accept them. +In this case the descriptors are closed, with pending data either discarded +in the case of the unreliable datagram protocol or preserved in the case of a +reliable protocol. +The pending data can be retrieved with another call to +.Fn recvmsg . +.It Bq Er EMSGSIZE +The +.Fa msg_iovlen +member of the +.Fa msghdr +structure pointed to by +.Fa msg +is less than or equal to 0, or is greater than +.Va IOV_MAX . +.It Bq Er EAGAIN +The socket is marked non-blocking and the receive operation +would block, or +a receive timeout had been set +and the timeout expired before data were received. +.It Bq Er EINTR +The receive was interrupted by delivery of a signal before +any data were available. +.It Bq Er EFAULT +The receive buffer pointer(s) point outside the process's +address space. +.El +.Sh SEE ALSO +.Xr fcntl 2 , +.Xr getsockopt 2 , +.Xr read 2 , +.Xr select 2 , +.Xr socket 2 , +.Xr CMSG_DATA 3 , +.Xr unix 4 +.Sh HISTORY +The +.Fn recv +function appeared in +.Bx 4.2 . +The +.Fn recvmmsg +function appeared in +.Fx 11.0 . diff --git a/lib/libsys/recvmmsg.c b/lib/libsys/recvmmsg.c new file mode 100644 index 000000000000..c03fe98c37ef --- /dev/null +++ b/lib/libsys/recvmmsg.c @@ -0,0 +1,95 @@ +/* + * Copyright (c) 2016 Boris Astardzhiev, Smartcom-Bulgaria AD + * All rights reserved. + * + * 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(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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. + */ + +#include <sys/types.h> +#include <sys/socket.h> +#include <errno.h> +#include <poll.h> +#include <stddef.h> +#include <ssp/ssp.h> +#include "libc_private.h" + +ssize_t +__ssp_real(recvmmsg)(int s, struct mmsghdr *__restrict msgvec, size_t vlen, + int flags, const struct timespec *__restrict timeout) +{ + struct pollfd pfd[1]; + size_t i, rcvd; + ssize_t ret; + int res; + short ev; + + if (timeout != NULL) { + pfd[0].fd = s; + pfd[0].revents = 0; + pfd[0].events = ev = POLLIN | POLLRDNORM | POLLRDBAND | + POLLPRI; + res = ppoll(&pfd[0], 1, timeout, NULL); + if (res == -1 || res == 0) + return (res); + if (pfd[0].revents & POLLNVAL) { + errno = EBADF; + return (-1); + } + if ((pfd[0].revents & ev) == 0) { + errno = ETIMEDOUT; + return (-1); + } + } + + ret = __sys_recvmsg(s, &msgvec[0].msg_hdr, flags); + if (ret == -1) + return (ret); + + msgvec[0].msg_len = ret; + + /* + * Do non-blocking receive for second and later messages if + * WAITFORONE is set. + */ + if (flags & MSG_WAITFORONE) + flags |= MSG_DONTWAIT; + + rcvd = 1; + for (i = rcvd; i < vlen; i++, rcvd++) { + ret = __sys_recvmsg(s, &msgvec[i].msg_hdr, flags); + if (ret == -1) { + /* We have received messages. Let caller know + * about the data received, socket error is + * returned on next invocation. + */ + return (rcvd); + } + + /* Save received bytes. */ + msgvec[i].msg_len = ret; + } + + return (rcvd); +} diff --git a/lib/libsys/rename.2 b/lib/libsys/rename.2 new file mode 100644 index 000000000000..4faba81ff509 --- /dev/null +++ b/lib/libsys/rename.2 @@ -0,0 +1,343 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd August 25, 2024 +.Dt RENAME 2 +.Os +.Sh NAME +.Nm rename +.Nd change the name of a file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft int +.Fn rename "const char *from" "const char *to" +.Ft int +.Fn renameat "int fromfd" "const char *from" "int tofd" "const char *to" +.Sh DESCRIPTION +The +.Fn rename +system call +causes the link named +.Fa from +to be renamed as +.Fa to . +If +.Fa to +exists, it is first removed. +Both +.Fa from +and +.Fa to +must be of the same type (that is, both directories or both +non-directories), and must reside on the same file system. +.Pp +The +.Fn rename +system call +guarantees that if +.Fa to +already exists, an instance of +.Fa to +will always exist, even if the system should crash in +the middle of the operation. +.Pp +If the final component of +.Fa from +is a symbolic link, +the symbolic link is renamed, +not the file or directory to which it points. +.Pp +If +.Fa from +and +.Fa to +resolve to the same directory entry, or to different directory +entries for the same existing file, +.Fn rename +returns success without taking any further action. +.Pp +The +.Fn renameat +system call is equivalent to +.Fn rename +except in the case where either +.Fa from +or +.Fa to +specifies a relative path. +If +.Fa from +is a relative path, the file to be renamed is located +relative to the directory associated with the file descriptor +.Fa fromfd +instead of the current working directory. +If the +.Fa to +is a relative path, the same happens only relative to the directory associated +with +.Fa tofd . +If the +.Fn renameat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fromfd +or +.Fa tofd +parameter, the current working directory is used in the determination +of the file for the respective path parameter. +.\".Sh CAVEAT +.\"The system can deadlock if a loop in the file system graph is present. +.\"This loop takes the form of an entry in directory +.\".Pa a , +.\"say +.\".Pa a/foo , +.\"being a hard link to directory +.\".Pa b , +.\"and an entry in +.\"directory +.\".Pa b , +.\"say +.\".Pa b/bar , +.\"being a hard link +.\"to directory +.\".Pa a . +.\"When such a loop exists and two separate processes attempt to +.\"perform +.\".Ql rename a/foo b/bar +.\"and +.\".Ql rename b/bar a/foo , +.\"respectively, +.\"the system may deadlock attempting to lock +.\"both directories for modification. +.\"Hard links to directories should be +.\"replaced by symbolic links by the system administrator. +.Sh RETURN VALUES +.Rv -std rename +.Sh ERRORS +The +.Fn rename +system call +will fail and neither of the argument files will be +affected if: +.Bl -tag -width Er +.It Bq Er ENAMETOOLONG +A component of either pathname exceeded 255 characters, +or the entire length of either path name exceeded 1023 characters. +.It Bq Er ENOENT +A component of the +.Fa from +path does not exist, +or a path prefix of +.Fa to +does not exist. +.It Bq Er EACCES +A component of either path prefix denies search permission. +.It Bq Er EACCES +The requested link requires writing in a directory with a mode +that denies write permission. +.It Bq Er EACCES +The directory pointed at by the +.Fa from +argument denies write permission, and the operation would move +it to another parent directory. +.It Bq Er EPERM +The file pointed at by the +.Fa from +argument has its immutable, undeletable or append-only flag set, see the +.Xr chflags 2 +manual page for more information. +.It Bq Er EPERM +The parent directory of the file pointed at by the +.Fa from +argument has its immutable or append-only flag set. +.It Bq Er EPERM +The parent directory of the file pointed at by the +.Fa to +argument has its immutable flag set. +.It Bq Er EPERM +The directory containing +.Fa from +is marked sticky, +and neither the containing directory nor +.Fa from +are owned by the effective user ID. +.It Bq Er EPERM +The file pointed at by the +.Fa to +argument +exists, +the directory containing +.Fa to +is marked sticky, +and neither the containing directory nor +.Fa to +are owned by the effective user ID. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating either pathname. +.It Bq Er ENOTDIR +A component of either path prefix is not a directory. +.It Bq Er ENOTDIR +The +.Fa from +argument +is a directory, but +.Fa to +is not a directory. +.It Bq Er EISDIR +The +.Fa to +argument +is a directory, but +.Fa from +is not a directory. +.It Bq Er EXDEV +The link named by +.Fa to +and the file named by +.Fa from +are on different logical devices (file systems). +Note that this error +code will not be returned if the implementation permits cross-device +links. +.It Bq Er ENOSPC +The directory in which the entry for the new name is being placed +cannot be extended because there is no space left on the file +system containing the directory. +.It Bq Er EDQUOT +The directory in which the entry for the new name +is being placed cannot be extended because the +user's quota of disk blocks on the file system +containing the directory has been exhausted. +.It Bq Er EIO +An I/O error occurred while making or updating a directory entry. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.It Bq Er EROFS +The requested link requires writing in a directory on a read-only file +system. +.It Bq Er EFAULT +Path +points outside the process's allocated address space. +.It Bq Er EINVAL +The +.Fa from +argument +is a parent directory of +.Fa to , +or an attempt is made to rename +.Ql .\& +or +.Ql \&.. . +.It Bq Er EINVAL +The last component of the +.Fa to +path is invalid on the target file system. +.It Bq Er ENOTEMPTY +The +.Fa to +argument +is a directory and is not empty. +.It Bq Er ECAPMODE +.Fn rename +was called and the process is in capability mode. +.El +.Pp +In addition to the errors returned by the +.Fn rename , +the +.Fn renameat +may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa from +argument does not specify an absolute path and the +.Fa fromfd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching, or the +.Fa to +argument does not specify an absolute path and the +.Fa tofd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er ENOTDIR +The +.Fa from +argument is not an absolute path and +.Fa fromfd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory, or the +.Fa to +argument is not an absolute path and +.Fa tofd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.It Bq Er ECAPMODE +.Dv AT_FDCWD +is specified and the process is in capability mode. +.It Bq Er ENOTCAPABLE +.Fa path +is an absolute path or contained a ".." component leading to a directory +outside of the directory hierarchy specified by +.Fa fromfd +or +.Fa tofd . +.It Bq Er ENOTCAPABLE +The +.Fa fromfd +file descriptor lacks the +.Dv CAP_RENAMEAT_SOURCE +right, or the +.Fa tofd +file descriptor lacks the +.Dv CAP_RENAMEAT_TARGET +right. +.El +.Sh SEE ALSO +.Xr chflags 2 , +.Xr open 2 , +.Xr symlink 7 +.Sh STANDARDS +The +.Fn rename +system call is expected to conform to +.St -p1003.1-96 . +The +.Fn renameat +system call follows The Open Group Extended API Set 2 specification. +.Sh HISTORY +The +.Fn renameat +system call appeared in +.Fx 8.0 . diff --git a/lib/libsys/revoke.2 b/lib/libsys/revoke.2 new file mode 100644 index 000000000000..f5ae1e92c357 --- /dev/null +++ b/lib/libsys/revoke.2 @@ -0,0 +1,107 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Berkeley Software Design, Inc. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd January 25, 2016 +.Dt REVOKE 2 +.Os +.Sh NAME +.Nm revoke +.Nd revoke file access +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn revoke "const char *path" +.Sh DESCRIPTION +The +.Fn revoke +system call invalidates all current open file descriptors in the system +for the file named by +.Fa path . +Subsequent operations on any such descriptors +fail, with the exceptions that a +.Fn read +from a character device file which has been revoked +returns a count of zero (end of file), +and a +.Fn close +system call will succeed. +If the file is a special file for a device which is open, +the device close function +is called as if all open references to the file had been closed +using a special close method which does not block. +.Pp +Access to a file may be revoked only by its owner or the super user. +The +.Fn revoke +system call is currently supported only for block and character special +device files. +It is normally used to prepare a terminal device for a new login session, +preventing any access by a previous user of the terminal. +.Sh RETURN VALUES +.Rv -std revoke +.Sh ERRORS +Access to the named file is revoked unless one of the following: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1024 characters. +.It Bq Er ENOENT +The named file or a component of the path name does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.It Bq Er EINVAL +The implementation does not support the +.Fn revoke +operation on the named file. +.It Bq Er EPERM +The caller is neither the owner of the file nor the super user. +.El +.Sh SEE ALSO +.Xr revoke 1 , +.Xr close 2 +.Sh HISTORY +The +.Fn revoke +system call first appeared in +.Bx 4.3 Reno . +.Sh BUGS +The non-blocking close method is only correctly implemented for +terminal devices. diff --git a/lib/libsys/rfork.2 b/lib/libsys/rfork.2 new file mode 100644 index 000000000000..649b2acae6ce --- /dev/null +++ b/lib/libsys/rfork.2 @@ -0,0 +1,203 @@ +.\" +.\" This manual page is taken directly from Plan9, and modified to +.\" describe the actual BSD implementation. Permission for +.\" use of this page comes from Rob Pike <rob@plan9.att.com>. +.\" +.Dd September 25, 2019 +.Dt RFORK 2 +.Os +.Sh NAME +.Nm rfork +.Nd manipulate process resources +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft pid_t +.Fn rfork "int flags" +.Sh DESCRIPTION +Forking, vforking or rforking are the only ways new processes are created. +The +.Fa flags +argument to +.Fn rfork +selects which resources of the +invoking process (parent) are shared +by the new process (child) or initialized to +their default values. +The resources include +the open file descriptor table (which, when shared, permits processes +to open and close files for other processes), +and open files. +The +.Fa flags +argument +is either +.Dv RFSPAWN +or the logical OR of some subset of: +.Bl -tag -width ".Dv RFLINUXTHPN" +.It Dv RFPROC +If set a new process is created; otherwise changes affect the +current process. +.It Dv RFNOWAIT +If set, the child process will be dissociated from the parent. +Upon +exit the child will not leave a status for the parent to collect. +See +.Xr wait 2 . +.It Dv RFFDG +If set, the invoker's file descriptor table (see +.Xr intro 2 ) +is copied; otherwise the two processes share a +single table. +.It Dv RFCFDG +If set, the new process starts with a clean file descriptor table. +Is mutually exclusive with +.Dv RFFDG . +.It Dv RFTHREAD +If set, the new process shares file descriptor to process leaders table +with its parent. +Only applies when neither +.Dv RFFDG +nor +.Dv RFCFDG +are set. +.It Dv RFMEM +If set, the kernel will force sharing of the entire address space, +typically by sharing the hardware page table directly. +The child +will thus inherit and share all the segments the parent process owns, +whether they are normally shareable or not. +The stack segment is +not split (both the parent and child return on the same stack) and thus +.Fn rfork +with the RFMEM flag may not generally be called directly from high level +languages including C. +May be set only with +.Dv RFPROC . +A helper function is provided to assist with this problem and will cause +the new process to run on the provided stack. +See +.Xr rfork_thread 3 +for information. +Note that a lot of code will not run correctly in such an environment. +.It Dv RFSIGSHARE +If set, the kernel will force sharing the sigacts structure between the +child and the parent. +.It Dv RFTSIGZMB +If set, the kernel will deliver a specified signal to the parent +upon the child exit, instead of default SIGCHLD. +The signal number +.Dv signum +is specified by oring the +.Dv RFTSIGFLAGS(signum) +expression into +.Fa flags . +Specifying signal number 0 disables signal delivery upon the child exit. +.It Dv RFLINUXTHPN +If set, the kernel will deliver SIGUSR1 instead of SIGCHLD upon thread +exit for the child. +This is intended to mimic certain Linux clone behaviour. +.El +.Pp +File descriptors in a shared file descriptor table are kept +open until either they are explicitly closed +or all processes sharing the table exit. +.Pp +If +.Dv RFSPAWN +is passed, +.Nm +will use +.Xr vfork 2 +semantics but reset all signal actions in the child to default. +This flag is used by the +.Xr posix_spawn 3 +implementation in libc. +.Pp +If +.Dv RFPROC +is set, the +value returned in the parent process +is the process id +of the child process; the value returned in the child is zero. +Without +.Dv RFPROC , +the return value is zero. +Process id's range from 1 to the maximum integer +.Ft ( int ) +value. +The +.Fn rfork +system call +will sleep, if necessary, until required process resources are available. +.Pp +The +.Fn fork +system call +can be implemented as a call to +.Fn rfork "RFFDG | RFPROC" +but is not for backwards compatibility. +.Sh RETURN VALUES +Upon successful completion, +.Fn rfork +returns a value +of 0 to the child process and returns the process ID of the child +process to the parent process. +Otherwise, a value of -1 is returned +to the parent process, no child process is created, and the global +variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn rfork +system call +will fail and no child process will be created if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The system-imposed limit on the total +number of processes under execution would be exceeded. +The limit is given by the +.Xr sysctl 3 +MIB variable +.Dv KERN_MAXPROC . +(The limit is actually ten less than this +except for the super user). +.It Bq Er EAGAIN +The user is not the super user, and +the system-imposed limit +on the total number of +processes under execution by a single user would be exceeded. +The limit is given by the +.Xr sysctl 3 +MIB variable +.Dv KERN_MAXPROCPERUID . +.It Bq Er EAGAIN +The user is not the super user, and +the soft resource limit corresponding to the +.Fa resource +argument +.Dv RLIMIT_NOFILE +would be exceeded (see +.Xr getrlimit 2 ) . +.It Bq Er EINVAL +Both the RFFDG and the RFCFDG flags were specified. +.It Bq Er EINVAL +Any flags not listed above were specified. +.It Bq Er EINVAL +An invalid signal number was specified. +.It Bq Er ENOMEM +There is insufficient swap space for the new process. +.El +.Sh SEE ALSO +.Xr fork 2 , +.Xr intro 2 , +.Xr minherit 2 , +.Xr vfork 2 , +.Xr pthread_create 3 , +.Xr rfork_thread 3 +.Sh HISTORY +The +.Fn rfork +function first appeared in Plan9. diff --git a/lib/libsys/rfork_thread.3 b/lib/libsys/rfork_thread.3 new file mode 100644 index 000000000000..0ade53b8afb6 --- /dev/null +++ b/lib/libsys/rfork_thread.3 @@ -0,0 +1,85 @@ +.\" +.\" Copyright (c) 2000 Peter Wemm <peter@FreeBSD.org> +.\" All rights reserved. +.\" +.\" 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. +.\" +.Dd February 6, 2011 +.Dt RFORK_THREAD 3 +.Os +.Sh NAME +.Nm rfork_thread +.Nd create a rfork-based process thread +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft pid_t +.Fn rfork_thread "int flags" "void *stack" "int (*func)(void *arg)" "void *arg" +.Sh DESCRIPTION +.Bf -symbolic +The +.Fn rfork_thread +function has been deprecated in favor of +.Xr pthread_create 3 . +.Ef +.Pp +The +.Fn rfork_thread +function +is a helper function for +.Xr rfork 2 . +It arranges for a new process to be created and the child process will +call the specified function with the specified argument, while running on +the supplied stack. +.Pp +Using this function should avoid the need to implement complex stack +swap code. +.Sh RETURN VALUES +Upon successful completion, +.Fn rfork_thread +returns the process ID of the child process to the parent process. +Otherwise, a value of -1 is returned +to the parent process, no child process is created, and the global +variable +.Va errno +is set to indicate the error. +.Pp +The child process context is not aware of a return from the +.Fn rfork_thread +function as it begins executing directly with the supplied function. +.Sh ERRORS +See +.Xr rfork 2 +for error return codes. +.Sh SEE ALSO +.Xr fork 2 , +.Xr intro 2 , +.Xr minherit 2 , +.Xr rfork 2 , +.Xr vfork 2 , +.Xr pthread_create 3 +.Sh HISTORY +The +.Fn rfork_thread +function first appeared in +.Fx 4.3 . diff --git a/lib/libsys/riscv/Makefile.sys b/lib/libsys/riscv/Makefile.sys new file mode 100644 index 000000000000..2ff84735f484 --- /dev/null +++ b/lib/libsys/riscv/Makefile.sys @@ -0,0 +1,5 @@ +SRCS+= __vdso_gettc.c \ + sched_getcpu_gen.c + +MDASM= cerror.S \ + vfork.S diff --git a/lib/libsys/riscv/SYS.h b/lib/libsys/riscv/SYS.h new file mode 100644 index 000000000000..c2d93c567e2b --- /dev/null +++ b/lib/libsys/riscv/SYS.h @@ -0,0 +1,63 @@ +/*- + * Copyright (c) 2014 Andrew Turner + * Copyright (c) 2015 Ruslan Bukin <br@bsdpad.com> + * All rights reserved. + * + * Portions of this software were developed by SRI International and the + * University of Cambridge Computer Laboratory under DARPA/AFRL contract + * FA8750-10-C-0237 ("CTSRD"), as part of the DARPA CRASH research programme. + * + * Portions of this software were developed by the University of Cambridge + * Computer Laboratory as part of the CTSRD Project, with support from the + * UK Higher Education Innovation Fund (HEIF). + * + * 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. + */ + +#include <sys/syscall.h> +#include <machine/asm.h> + +#define _SYSCALL(name) \ + li t0, SYS_ ## name; \ + ecall + +#ifndef _SYSCALL_BODY +#define _SYSCALL_BODY(name) \ + _SYSCALL(name); \ + bnez t0, 1f; \ + ret; \ +1: la t1, cerror; \ + jr t1 +#endif + +#define PSEUDO(name) \ +ENTRY(__sys_##name); \ + WEAK_REFERENCE(__sys_##name, _##name); \ + _SYSCALL_BODY(name); \ +END(__sys_##name) + +#define RSYSCALL(name) \ +ENTRY(__sys_##name); \ + WEAK_REFERENCE(__sys_##name, name); \ + WEAK_REFERENCE(__sys_##name, _##name); \ + _SYSCALL_BODY(name); \ +END(__sys_##name) diff --git a/lib/libsys/riscv/__vdso_gettc.c b/lib/libsys/riscv/__vdso_gettc.c new file mode 100644 index 000000000000..5037debef461 --- /dev/null +++ b/lib/libsys/riscv/__vdso_gettc.c @@ -0,0 +1,53 @@ +/*- + * Copyright (c) 2021 Jessica Clarke + * + * 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. + */ + +#include <sys/types.h> +#include <sys/elf.h> +#include <sys/time.h> +#include <sys/vdso.h> + +#include <machine/riscvreg.h> + +#include <errno.h> + +#include "libc_private.h" + +#pragma weak __vdso_gettc +int +__vdso_gettc(const struct vdso_timehands *th, u_int *tc) +{ + if (th->th_algo != VDSO_TH_ALGO_RISCV_RDTIME) + return (ENOSYS); + + *tc = csr_read(time); + return (0); +} + +#pragma weak __vdso_gettimekeep +int +__vdso_gettimekeep(struct vdso_timekeep **tk) +{ + return (_elf_aux_info(AT_TIMEKEEP, tk, sizeof(*tk))); +} diff --git a/lib/libsys/riscv/cerror.S b/lib/libsys/riscv/cerror.S new file mode 100644 index 000000000000..34129b1ac8be --- /dev/null +++ b/lib/libsys/riscv/cerror.S @@ -0,0 +1,48 @@ +/*- + * Copyright (c) 2015 Ruslan Bukin <br@bsdpad.com> + * All rights reserved. + * + * Portions of this software were developed by SRI International and the + * University of Cambridge Computer Laboratory under DARPA/AFRL contract + * FA8750-10-C-0237 ("CTSRD"), as part of the DARPA CRASH research programme. + * + * Portions of this software were developed by the University of Cambridge + * Computer Laboratory as part of the CTSRD Project, with support from the + * UK Higher Education Innovation Fund (HEIF). + * + * 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. + */ + +#include <machine/asm.h> +ENTRY(cerror) + addi sp, sp, -16 + sd a0, 0(sp) + sd ra, 8(sp) + call _C_LABEL(__error) + ld a1, 0(sp) + ld ra, 8(sp) + sw a1, 0(a0) + li a0, -1 + li a1, -1 + addi sp, sp, 16 + ret +END(cerror) diff --git a/lib/libsys/riscv/vfork.S b/lib/libsys/riscv/vfork.S new file mode 100644 index 000000000000..62c890badbb8 --- /dev/null +++ b/lib/libsys/riscv/vfork.S @@ -0,0 +1,52 @@ +/*- + * Copyright (c) 2015 Ruslan Bukin <br@bsdpad.com> + * All rights reserved. + * + * Portions of this software were developed by SRI International and the + * University of Cambridge Computer Laboratory under DARPA/AFRL contract + * FA8750-10-C-0237 ("CTSRD"), as part of the DARPA CRASH research programme. + * + * Portions of this software were developed by the University of Cambridge + * Computer Laboratory as part of the CTSRD Project, with support from the + * UK Higher Education Innovation Fund (HEIF). + * + * 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. + */ + +#include <machine/asm.h> +#include "SYS.h" + +ENTRY(__sys_vfork) + WEAK_REFERENCE(__sys_vfork, vfork) + WEAK_REFERENCE(__sys_vfork, _vfork) + mv a2, ra + + _SYSCALL(vfork) + bnez t0, 1f + addi a1, a1, -1 + and a0, a0, a1 + mv ra, a2 + + ret +1: la t1, cerror + jr t1 +END(__sys_vfork) diff --git a/lib/libsys/rmdir.2 b/lib/libsys/rmdir.2 new file mode 100644 index 000000000000..6efeb8f4856f --- /dev/null +++ b/lib/libsys/rmdir.2 @@ -0,0 +1,117 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd March 30, 2020 +.Dt RMDIR 2 +.Os +.Sh NAME +.Nm rmdir +.Nd remove a directory file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn rmdir "const char *path" +.Sh DESCRIPTION +The +.Fn rmdir +system call +removes a directory file +whose name is given by +.Fa path . +The directory must not have any entries other +than +.Ql .\& +and +.Ql \&.. . +.Sh RETURN VALUES +.Rv -std rmdir +.Sh ERRORS +The named file is removed unless: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named directory does not exist. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er ENOTEMPTY +The named directory contains files other than +.Ql .\& +and +.Ql ..\& +in it. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er EACCES +Write permission is denied on the directory containing the link +to be removed. +.It Bq Er EPERM +The directory to be removed has its immutable, undeletable or append-only flag +set, see the +.Xr chflags 2 +manual page for more information. +.It Bq Er EPERM +The parent directory of the directory to be removed has its immutable or +append-only flag set. +.It Bq Er EPERM +The directory containing the directory to be removed is marked sticky, +and neither the containing directory nor the directory to be removed +are owned by the effective user ID. +.It Bq Er EINVAL +The last component of the path is +.Ql .\& +or +.Ql .. . +.It Bq Er EBUSY +The directory to be removed is the mount point +for a mounted file system. +.It Bq Er EIO +An I/O error occurred while deleting the directory entry +or deallocating the inode. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.It Bq Er EROFS +The directory entry to be removed resides on a read-only file system. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.El +.Sh SEE ALSO +.Xr mkdir 2 , +.Xr unlink 2 +.Sh HISTORY +The +.Fn rmdir +system call appeared in +.Bx 4.2 . diff --git a/lib/libsys/rtprio.2 b/lib/libsys/rtprio.2 new file mode 100644 index 000000000000..011ec58d3259 --- /dev/null +++ b/lib/libsys/rtprio.2 @@ -0,0 +1,204 @@ +.\"- +.\" Copyright (c) 1994, Henrik Vestergaard Draboel +.\" All rights reserved. +.\" +.\" 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. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by Henrik Vestergaard Draboel. +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" 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. +.\"- +.\" Copyright (c) 2011 Xin LI <delphij@FreeBSD.org> +.\" +.\" 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. +.\" +.Dd December 8, 2021 +.Dt RTPRIO 2 +.Os +.Sh NAME +.Nm rtprio , +.Nm rtprio_thread +.Nd examine or modify realtime or idle priority +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/rtprio.h +.Ft int +.Fn rtprio "int function" "pid_t pid" "struct rtprio *rtp" +.Ft int +.Fn rtprio_thread "int function" "lwpid_t lwpid" "struct rtprio *rtp" +.Sh DESCRIPTION +The +.Fn rtprio +system call +is used to lookup or change the realtime or idle priority of a process, +or the calling thread. +The +.Fn rtprio_thread +system call +is used to lookup or change the realtime or idle priority of a thread. +.Pp +The +.Fa function +argument +specifies the operation to be performed. +RTP_LOOKUP to lookup the current priority, +and RTP_SET to set the priority. +.Pp +For the +.Fn rtprio +system call, +the +.Fa pid +argument +specifies the process to operate on, +0 for the calling thread. +When +.Fa pid +is non-zero, +the system call reports the highest priority in the process, +or sets all threads' priority in the process, +depending on value of the +.Fa function +argument. +.Pp +For the +.Fn rtprio_thread +system call, +the +.Fa lwpid +specifies the thread to operate on, +0 for the calling thread. +.Pp +The +.Fa *rtp +argument +is a pointer to a struct rtprio which is used to specify the priority and priority type. +This structure has the following form: +.Bd -literal +struct rtprio { + u_short type; + u_short prio; +}; +.Ed +.Pp +The value of the +.Va type +field may be RTP_PRIO_REALTIME for realtime priorities, +RTP_PRIO_NORMAL for normal priorities, and RTP_PRIO_IDLE for idle priorities. +The priority specified by the +.Va prio +field ranges between 0 and +.Dv RTP_PRIO_MAX +.Pq usually 31 . +0 is the highest possible priority. +.Pp +Realtime and idle priority is inherited through +.Fn fork +and +.Fn exec . +.Pp +A realtime thread can only be preempted by a thread of equal or +higher priority, or by an interrupt; idle priority threads will run only +when no other real/normal priority thread is runnable. +Higher real/idle priority threads +preempt lower real/idle priority threads. +Threads of equal real/idle priority are run round-robin. +.Sh RETURN VALUES +.Rv -std rtprio rtprio_thread +.Sh ERRORS +The +.Fn rtprio +and +.Fn rtprio_thread +system calls +will fail if: +.Bl -tag -width Er +.It Bq Er EFAULT +The rtp pointer passed to +.Fn rtprio +or +.Fn rtprio_thread +was invalid. +.It Bq Er EINVAL +The specified +.Fa prio +was out of range. +.It Bq Er EPERM +The calling thread is not allowed to set the priority. +Only +root is allowed to change the realtime or idle priority of any thread. +Exceptional privileges can be granted through the +.Xr mac_priority 4 +policy and the realtime and idletime user groups. +The +.Xr sysctl 8 +variable +.Va security.bsd.unprivileged_idprio +is deprecated. +If set to non-zero, it lets any user change the idle priority of threads +they own. +.It Bq Er ESRCH +The specified process or thread was not found or visible. +.El +.Sh SEE ALSO +.Xr nice 1 , +.Xr ps 1 , +.Xr rtprio 1 , +.Xr setpriority 2 , +.Xr nice 3 , +.Xr mac_priority 4 , +.Xr renice 8 , +.Xr p_cansee 9 +.Sh AUTHORS +.An -nosplit +The original author was +.An Henrik Vestergaard Draboel Aq Mt hvd@terry.ping.dk . +This implementation in +.Fx +was substantially rewritten by +.An David Greenman . +The +.Fn rtprio_thread +system call was implemented by +.An David Xu . diff --git a/lib/libsys/sched_get_priority_max.2 b/lib/libsys/sched_get_priority_max.2 new file mode 100644 index 000000000000..81cd502469dc --- /dev/null +++ b/lib/libsys/sched_get_priority_max.2 @@ -0,0 +1,121 @@ +.\" Copyright (c) 1998 HD Associates, Inc. +.\" All rights reserved. +.\" +.\" 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. +.\" +.Dd March 12, 1998 +.Dt SCHED_GET_PRIORITY_MAX 2 +.Os +.Sh NAME +.Nm sched_get_priority_max , +.Nm sched_get_priority_min , +.Nm sched_rr_get_interval +.Nd get scheduling parameter limits +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sched.h +.Ft int +.Fn sched_get_priority_max "int policy" +.Ft int +.Fn sched_get_priority_min "int policy" +.Ft int +.Fn sched_rr_get_interval "pid_t pid" "struct timespec *interval" +.Sh DESCRIPTION +The +.Fn sched_get_priority_max +and +.Fn sched_get_priority_min +system calls return the appropriate maximum or minimum, respectively, +for the scheduling policy specified by +.Fa policy . +The +.Fn sched_rr_get_interval +system call updates the +.Fa timespec +structure referenced by the +.Fa interval +argument to contain the current execution time limit (i.e., time +quantum) for the process specified by +.Fa pid . +If +.Fa pid +is zero, the current execution time limit for the calling process is +returned. +.Pp +The value of +.Fa policy +should be one of the scheduling policy values defined in +.Fa <sched.h> : +.Bl -tag -width [SCHED_OTHER] +.It Bq Er SCHED_FIFO +First-in-first-out fixed priority scheduling with no round robin scheduling; +.It Bq Er SCHED_OTHER +The standard time sharing scheduler; +.It Bq Er SCHED_RR +Round-robin scheduling across same priority processes. +.El +.Sh RETURN VALUES +If successful, the +.Fn sched_get_priority_max +and +.Fn sched_get_priority_min +system calls shall return the appropriate maximum or minimum values, +respectively. +If unsuccessful, they shall return a value of -1 and set +.Fa errno +to indicate the error. +.Pp +.Rv -std sched_rr_get_interval +.Sh ERRORS +On failure +.Va errno +will be set to the corresponding value: +.Bl -tag -width Er +.It Bq Er EINVAL +The value of the +.Fa policy +argument does not represent a defined scheduling policy. +.It Bq Er ENOSYS +The +.Fn sched_get_priority_max , +.Fn sched_get_priority_min , +and +.Fn sched_rr_get_interval +system calls are not supported by the implementation. +.It Bq Er ESRCH +No process can be found corresponding to that specified by +.Fa pid . +.El +.Sh SEE ALSO +.Xr sched_getparam 2 , +.Xr sched_getscheduler 2 , +.Xr sched_setparam 2 , +.Xr sched_setscheduler 2 +.Sh STANDARDS +The +.Fn sched_get_priority_max , +.Fn sched_get_priority_min , +and +.Fn sched_rr_get_interval +system calls conform to +.St -p1003.1b-93 . diff --git a/lib/libsys/sched_getcpu.3 b/lib/libsys/sched_getcpu.3 new file mode 100644 index 000000000000..050a8f3facb4 --- /dev/null +++ b/lib/libsys/sched_getcpu.3 @@ -0,0 +1,51 @@ +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2024 The FreeBSD Foundation +.\" +.\" This documentation was written by Ed Maste <emaste@FreeBSD.org> +.\" under sponsorship from the FreeBSD Foundation. +.\" +.Dd November 13, 2024 +.Dt SCHED_GETCPU 3 +.Os +.Sh NAME +.Nm sched_getcpu +.Nd get current CPU +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sched.h +.Ft int +.Fn sched_getcpu void +.Sh DESCRIPTION +The +.Fn sched_getcpu +function returns the current CPU on which the calling thread is running. +.Sh RETURN VALUES +.Fn sched_getcpu +returns the 0-based index of the current CPU at the time of the call. +The value may become invalid immediately after return, unless the thread is +pinned to a specific CPU. +CPU numbering is the same as used by +.Xr cpuset 2 +and CPU affinity calls. +.Pp +There are no error values as +.Fn sched_getcpu +does not fail. +.Sh SEE ALSO +.Xr cpuset 2 , +.Xr cpuset_getaffinity 2 , +.Xr cpuset_setaffinity 2 , +.Xr pthread_getaffinity_np 3 , +.Xr pthread_setaffinity_np +.Sh STANDARDS +The +.Nm +function originated in Linux. +This implementation aims to be source-compatible with the Linux implementation. +.Sh HISTORY +The +.Nm +function was introduced in +.Fx 13.1 . diff --git a/lib/libsys/sched_getcpu_gen.c b/lib/libsys/sched_getcpu_gen.c new file mode 100644 index 000000000000..ef1bebc2915a --- /dev/null +++ b/lib/libsys/sched_getcpu_gen.c @@ -0,0 +1,36 @@ +/*- + * Copyright (c) 2021 The FreeBSD Foundation + * + * This software were developed by Konstantin Belousov <kib@FreeBSD.org> + * under sponsorship from the FreeBSD Foundation. + * + * 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. + */ + +#include <sched.h> +#include "libc_private.h" + +int +sched_getcpu(void) +{ + return (__sys_sched_getcpu()); +} diff --git a/lib/libsys/sched_setparam.2 b/lib/libsys/sched_setparam.2 new file mode 100644 index 000000000000..68b07509ce83 --- /dev/null +++ b/lib/libsys/sched_setparam.2 @@ -0,0 +1,173 @@ +.\" Copyright (c) 1998 HD Associates, Inc. +.\" All rights reserved. +.\" +.\" 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. +.\" +.Dd March 12, 1998 +.Dt SCHED_SETPARAM 2 +.Os +.Sh NAME +.Nm sched_setparam , +.Nm sched_getparam +.Nd set/get scheduling parameters +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sched.h +.Ft int +.Fn sched_setparam "pid_t pid" "const struct sched_param *param" +.Ft int +.Fn sched_getparam "pid_t pid" "struct sched_param *param" +.Sh DESCRIPTION +The +.Fn sched_setparam +system call sets the scheduling parameters of the process specified by +.Fa pid +to the values specified by the +.Fa sched_param +structure pointed to by +.Fa param . +The value of the +.Fa sched_priority +member in the +.Fa param +structure must be any integer within the inclusive priority range for +the current scheduling policy of the process specified by +.Fa pid . +Higher numerical values for the priority represent higher priorities. +.Pp +In this implementation, if the value of +.Fa pid +is negative the system call will fail. +.Pp +If a process specified by +.Fa pid +exists and if the calling process has permission, the scheduling +parameters are set for the process whose process ID is equal to +.Fa pid . +.Pp +If +.Fa pid +is zero, the scheduling parameters are set for the calling process. +.Pp +In this implementation, the policy of when a process can affect +the scheduling parameters of another process is specified in +.St -p1003.1b-93 +as a write-style operation. +.Pp +The target process, whether it is running or not running, will resume +execution after all other runnable processes of equal or greater +priority have been scheduled to run. +.Pp +If the priority of the process specified by the +.Fa pid +argument is set higher than that of the lowest priority running process +and if the specified process is ready to run, the process specified by +the +.Fa pid +argument will preempt a lowest priority running process. +Similarly, if +the process calling +.Fn sched_setparam +sets its own priority lower than that of one or more other nonempty +process lists, then the process that is the head of the highest priority +list will also preempt the calling process. +Thus, in either case, the +originating process might not receive notification of the completion of +the requested priority change until the higher priority process has +executed. +.Pp +In this implementation, when the current scheduling policy for the +process specified by +.Fa pid +is normal timesharing (SCHED_OTHER, aka SCHED_NORMAL when not POSIX-source) +or the idle policy (SCHED_IDLE when not POSIX-source) then the behavior +is as if the process had been running under SCHED_RR with a priority +lower than any actual realtime priority. +.Pp +The +.Fn sched_getparam +system call will return the scheduling parameters of a process specified +by +.Fa pid +in the +.Fa sched_param +structure pointed to by +.Fa param . +.Pp +If a process specified by +.Fa pid +exists and if the calling process has permission, +the scheduling parameters for the process whose process ID is equal to +.Fa pid +are returned. +.Pp +In this implementation, the policy of when a process can obtain the +scheduling parameters of another process are detailed in +.St -p1003.1b-93 +as a read-style operation. +.Pp +If +.Fa pid +is zero, the scheduling parameters for the calling process will be +returned. +In this implementation, the +.Fa sched_getparam +system call will fail if +.Fa pid +is negative. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +On failure +.Va errno +will be set to the corresponding value: +.Bl -tag -width Er +.It Bq Er ENOSYS +The system is not configured to support this functionality. +.It Bq Er EPERM +The requesting process doesn not have permission as detailed in +.St -p1003.1b-93 . +.It Bq Er ESRCH +No process can be found corresponding to that specified by +.Fa pid . +.It Bq Er EINVAL +For +.Fn sched_setparam : +one or more of the requested scheduling parameters +is outside the range defined for the scheduling policy of the specified +.Fa pid . +.El +.Sh SEE ALSO +.Xr sched_get_priority_max 2 , +.Xr sched_get_priority_min 2 , +.Xr sched_getscheduler 2 , +.Xr sched_rr_get_interval 2 , +.Xr sched_setscheduler 2 , +.Xr sched_yield 2 +.Sh STANDARDS +The +.Fn sched_setparam +and +.Fn sched_getparam +system calls conform to +.St -p1003.1b-93 . diff --git a/lib/libsys/sched_setscheduler.2 b/lib/libsys/sched_setscheduler.2 new file mode 100644 index 000000000000..f4ddbf7feb03 --- /dev/null +++ b/lib/libsys/sched_setscheduler.2 @@ -0,0 +1,165 @@ +.\" Copyright (c) 1998 HD Associates, Inc. +.\" All rights reserved. +.\" +.\" 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. +.\" +.Dd March 12, 1998 +.Dt SCHED_SETSCHEDULER 2 +.Os +.Sh NAME +.Nm sched_setscheduler , +.Nm sched_getscheduler +.Nd set/get scheduling policy and scheduler parameters +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sched.h +.Ft int +.Fn sched_setscheduler "pid_t pid" "int policy" "const struct sched_param *param" +.Ft int +.Fn sched_getscheduler "pid_t pid" +.Sh DESCRIPTION +The +.Fn sched_setscheduler +system call sets the scheduling policy and scheduling parameters +of the process specified by +.Fa pid +to +.Fa policy +and the parameters specified in the +.Vt sched_param +structure pointed to by +.Fa param , +respectively. +The value of the +.Fa sched_priority +member in the +.Fa param +structure must be any integer within the inclusive priority range for +the scheduling policy specified by +.Fa policy . +.Pp +In this implementation, if the value of +.Fa pid +is negative the system call will fail. +.Pp +If a process specified by +.Fa pid +exists and if the calling process has permission, the scheduling +policy and scheduling parameters will be set for the process +whose process ID is equal to +.Fa pid . +.Pp +If +.Fa pid +is zero, the scheduling policy and scheduling +parameters are set for the calling process. +.Pp +In this implementation, the policy of when a process can affect +the scheduling parameters of another process is specified in +.St -p1003.1b-93 +as a write-style operation. +.Pp +The scheduling policies are in +.Fa <sched.h> : +.Bl -tag -width [SCHED_OTHER] +.It Bq Er SCHED_FIFO +First-in-first-out fixed priority scheduling with no round robin scheduling; +.It Bq Er SCHED_OTHER +The standard time sharing scheduler; +.It Bq Er SCHED_RR +Round-robin scheduling across same priority processes. +.El +.Pp +The +.Vt sched_param +structure is defined in +.Fa <sched.h> : +.Bd -literal -offset indent +struct sched_param { + int sched_priority; /* scheduling priority */ +}; +.Ed +.Pp +The +.Fn sched_getscheduler +system call returns the scheduling policy of the process specified +by +.Fa pid . +.Pp +If a process specified by +.Fa pid +exists and if the calling process has permission, +the scheduling parameters for the process whose process ID is equal to +.Fa pid +are returned. +.Pp +In this implementation, the policy of when a process can obtain the +scheduling parameters of another process are detailed in +.St -p1003.1b-93 +as a read-style operation. +.Pp +If +.Fa pid +is zero, the scheduling parameters for the calling process will be +returned. +In this implementation, the +.Fa sched_getscheduler +system call will fail if +.Fa pid +is negative. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +On failure +.Va errno +will be set to the corresponding value: +.Bl -tag -width Er +.It Bq Er ENOSYS +The system is not configured to support this functionality. +.It Bq Er EPERM +The requesting process doesn not have permission as detailed in +.St -p1003.1b-93 . +.It Bq Er ESRCH +No process can be found corresponding to that specified by +.Fa pid . +.It Bq Er EINVAL +The value of the +.Fa policy +argument is invalid, or one or more of the parameters contained in +.Fa param +is outside the valid range for the specified scheduling policy. +.El +.Sh SEE ALSO +.Xr sched_get_priority_max 2 , +.Xr sched_get_priority_min 2 , +.Xr sched_getparam 2 , +.Xr sched_rr_get_interval 2 , +.Xr sched_setparam 2 , +.Xr sched_yield 2 +.Sh STANDARDS +The +.Fn sched_setscheduler +and +.Fn sched_getscheduler +system calls conform to +.St -p1003.1b-93 . diff --git a/lib/libsys/sched_yield.2 b/lib/libsys/sched_yield.2 new file mode 100644 index 000000000000..61753757a7bf --- /dev/null +++ b/lib/libsys/sched_yield.2 @@ -0,0 +1,57 @@ +.\" Copyright (c) 1998 HD Associates, Inc. +.\" All rights reserved. +.\" +.\" 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. +.\" +.Dd March 12, 1998 +.Dt SCHED_YIELD 2 +.Os +.Sh NAME +.Nm sched_yield +.Nd yield processor +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sched.h +.Ft int +.Fn sched_yield void +.Sh DESCRIPTION +The +.Fn sched_yield +system call forces the running process to relinquish the processor until it +again becomes the head of its process list. +It takes no arguments. +.Sh RETURN VALUES +.Rv -std sched_yield +.Sh ERRORS +On failure +.Va errno +will be set to the corresponding value: +.Bl -tag -width Er +.It Bq Er ENOSYS +The system is not configured to support this functionality. +.El +.Sh STANDARDS +The +.Fn sched_yield +system call conforms to +.St -p1003.1b-93 . diff --git a/lib/libsys/sctp_generic_recvmsg.2 b/lib/libsys/sctp_generic_recvmsg.2 new file mode 100644 index 000000000000..124a1b7dc956 --- /dev/null +++ b/lib/libsys/sctp_generic_recvmsg.2 @@ -0,0 +1,72 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd October 30, 2007 +.Dt SCTP_GENERIC_RECVMSG 2 +.Os +.Sh NAME +.Nm sctp_generic_recvmsg +.Nd receive data from a peer +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netinet/sctp.h +.Ft int +.Fn sctp_generic_recvmsg "int s" "struct iovec *iov" "int iovlen" "struct sockaddr *from" "socklen_t *fromlen" "struct sctp_sndrcvinfo *sinfo" "int *msgflags" +.Sh DESCRIPTION +.Fn sctp_generic_recvmsg +is the true system call used by the +.Xr sctp_recvmsg 3 +function call. +This call is more efficient since it is a +true system call but it is specific to +.Fx +and can be expected +.Em not +to be present on any other operating +system. +For detailed usage please see the +.Xr sctp_recvmsg 3 +function call. +.Sh RETURN VALUES +The call returns the number of bytes read on success and -1 upon failure. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EBADF +The argument +.Fa s +is not a valid descriptor. +.It Bq Er ENOTSOCK +The argument +.Fa s +is not a socket. +.El +.Sh SEE ALSO +.Xr sctp_recvmsg 3 , +.Xr sctp 4 diff --git a/lib/libsys/sctp_generic_sendmsg.2 b/lib/libsys/sctp_generic_sendmsg.2 new file mode 100644 index 000000000000..66ce41ee2fcb --- /dev/null +++ b/lib/libsys/sctp_generic_sendmsg.2 @@ -0,0 +1,84 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd October 30, 2007 +.Dt SCTP_GENERIC_SENDMSG 2 +.Os +.Sh NAME +.Nm sctp_generic_sendmsg , +.Nm sctp_generic_sendmsg_iov +.Nd send data to a peer +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netinet/sctp.h +.Ft int +.Fn sctp_generic_sendmsg "int s" "void *msg" "int msglen" "struct sockaddr *to" "socklen_t len" "struct sctp_sndrcvinfo *sinfo" "int flags" +.Ft int +.Fn sctp_generic_sendmsg_iov "int s" "struct iovec *iov" "int iovlen" "struct sockaddr *to" "struct sctp_sndrcvinfo *sinfo" "int flags" +.Sh DESCRIPTION +.Fn sctp_generic_sendmsg +and +.Fn sctp_generic_sendmsg_iov +are the true system calls used by the +.Xr sctp_sendmsg 3 +and +.Xr sctp_send 3 +function calls. +These are more efficient since they are +true system calls but they are specific to +.Fx +and can be expected +.Em not +to be present on any other operating +system. +For detailed usage please see either the +.Xr sctp_send 3 +or +.Xr sctp_sendmsg 3 +function calls. +.Sh RETURN VALUES +The call returns the number of bytes written on success and -1 upon failure. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EBADF +The argument +.Fa s +is not a valid descriptor. +.It Bq Er ENOTSOCK +The argument +.Fa s +is not a socket. +.El +.Sh SEE ALSO +.Xr sctp_send 3 , +.Xr sctp_sendmsg 3 , +.Xr sctp_sendmsgx 3 , +.Xr sctp_sendx 3 , +.Xr sctp 4 diff --git a/lib/libsys/sctp_peeloff.2 b/lib/libsys/sctp_peeloff.2 new file mode 100644 index 000000000000..f31282e555db --- /dev/null +++ b/lib/libsys/sctp_peeloff.2 @@ -0,0 +1,78 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd February 2, 2024 +.Dt SCTP_PEELOFF 2 +.Os +.Sh NAME +.Nm sctp_peeloff +.Nd detach an association from a one-to-many socket to its own fd +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netinet/sctp.h +.Ft int +.Fn sctp_peeloff "int s" "sctp_assoc_t id" +.Sh DESCRIPTION +The +.Fn sctp_peeloff +system call attempts detach the association specified by +.Fa id +into its own separate socket. +.Sh RETURN VALUES +The call returns -1 on failure and the new socket descriptor +upon success. +.Sh ERRORS +The +.Fn sctp_peeloff +system call can return the following errors: +.Bl -tag -width Er +.It Bq Er ENOTCONN +The +.Fa id +given to the call does not map to a valid +association. +.It Bq Er E2BIG +The size of the address list exceeds the amount of +data provided. +.It Bq Er EBADF +The argument +.Fa s +is not a valid descriptor. +.It Bq Er ENOTSOCK +The argument +.Fa s +is not a socket. +.El +.Sh SEE ALSO +.Xr sctp 4 +.Sh STANDARDS +The +.Fn sctp_peeloff +function conforms to RFC 6458. diff --git a/lib/libsys/select.2 b/lib/libsys/select.2 new file mode 100644 index 000000000000..f79971a5876f --- /dev/null +++ b/lib/libsys/select.2 @@ -0,0 +1,225 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd June 25, 2020 +.Dt SELECT 2 +.Os +.Sh NAME +.Nm select +.Nd synchronous I/O multiplexing +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/select.h +.Ft int +.Fn select "int nfds" "fd_set *readfds" "fd_set *writefds" "fd_set *exceptfds" "struct timeval *timeout" +.Fn FD_SET fd &fdset +.Fn FD_CLR fd &fdset +.Fn FD_ISSET fd &fdset +.Fn FD_ZERO &fdset +.Sh DESCRIPTION +The +.Fn select +system call +examines the I/O descriptor sets whose addresses are passed in +.Fa readfds , +.Fa writefds , +and +.Fa exceptfds +to see if some of their descriptors +are ready for reading, are ready for writing, or have an exceptional +condition pending, respectively. +The only exceptional condition detectable is out-of-band +data received on a socket. +The first +.Fa nfds +descriptors are checked in each set; +i.e., the descriptors from 0 through +.Fa nfds Ns No -1 +in the descriptor sets are examined. +On return, +.Fn select +replaces the given descriptor sets +with subsets consisting of those descriptors that are ready +for the requested operation. +The +.Fn select +system call +returns the total number of ready descriptors in all the sets. +.Pp +The descriptor sets are stored as bit fields in arrays of integers. +The following macros are provided for manipulating such descriptor sets: +.Fn FD_ZERO &fdset +initializes a descriptor set +.Fa fdset +to the null set. +.Fn FD_SET fd &fdset +includes a particular descriptor +.Fa fd +in +.Fa fdset . +.Fn FD_CLR fd &fdset +removes +.Fa fd +from +.Fa fdset . +.Fn FD_ISSET fd &fdset +is non-zero if +.Fa fd +is a member of +.Fa fdset , +zero otherwise. +The behavior of these macros is undefined if +a descriptor value is less than zero or greater than or equal to +.Dv FD_SETSIZE , +which is normally at least equal +to the maximum number of descriptors supported by the system. +.Pp +If +.Fa timeout +is not a null pointer, it specifies the maximum interval to wait for the +selection to complete. +System activity can lengthen the interval by +an indeterminate amount. +.Pp +If +.Fa timeout +is a null pointer, the select blocks indefinitely. +.Pp +To effect a poll, the +.Fa timeout +argument should not be a null pointer, +but it should point to a zero-valued timeval structure. +.Pp +Any of +.Fa readfds , +.Fa writefds , +and +.Fa exceptfds +may be given as null pointers if no descriptors are of interest. +.Sh RETURN VALUES +The +.Fn select +system call +returns the number of ready descriptors that are contained in +the descriptor sets, +or -1 if an error occurred. +If the time limit expires, +.Fn select +returns 0. +If +.Fn select +returns with an error, +including one due to an interrupted system call, +the descriptor sets will be unmodified. +.Sh ERRORS +An error return from +.Fn select +indicates: +.Bl -tag -width Er +.It Bq Er EBADF +One of the descriptor sets specified an invalid descriptor. +.It Bq Er EFAULT +One of the arguments +.Fa readfds , writefds , exceptfds , +or +.Fa timeout +points to an invalid address. +.It Bq Er EINTR +A signal was delivered before the time limit expired and +before any of the selected events occurred. +.It Bq Er EINVAL +The specified time limit is invalid. +One of its components is +negative or too large. +.It Bq Er EINVAL +The +.Fa nfds +argument +was invalid. +.El +.Sh SEE ALSO +.Xr accept 2 , +.Xr connect 2 , +.Xr getdtablesize 2 , +.Xr gettimeofday 2 , +.Xr kqueue 2 , +.Xr poll 2 , +.Xr pselect 2 , +.Xr read 2 , +.Xr recv 2 , +.Xr send 2 , +.Xr write 2 , +.Xr clocks 7 +.Sh NOTES +The default size of +.Dv FD_SETSIZE +is currently 1024. +In order to accommodate programs which might potentially +use a larger number of open files with +.Fn select , +it is possible +to increase this size by having the program define +.Dv FD_SETSIZE +before the inclusion of any header which includes +.In sys/types.h . +.Pp +If +.Fa nfds +is greater than the number of open files, +.Fn select +is not guaranteed to examine the unused file descriptors. +For historical +reasons, +.Fn select +will always examine the first 256 descriptors. +.Sh STANDARDS +The +.Fn select +system call and +.Fn FD_CLR , +.Fn FD_ISSET , +.Fn FD_SET , +and +.Fn FD_ZERO +macros conform with +.St -p1003.1-2001 . +.Sh HISTORY +The +.Fn select +system call appeared in +.Bx 4.2 . +.Sh BUGS +.St -susv2 +allows systems to modify the original timeout in place. +Thus, it is unwise to assume that the timeout value will be unmodified +by the +.Fn select +system call. +.Fx +does not modify the return value, which can cause problems for applications +ported from other systems. diff --git a/lib/libsys/semctl.2 b/lib/libsys/semctl.2 new file mode 100644 index 000000000000..85657589eca6 --- /dev/null +++ b/lib/libsys/semctl.2 @@ -0,0 +1,200 @@ +.\" +.\" Copyright (c) 1995 David Hovemeyer <daveho@infocom.com> +.\" +.\" All rights reserved. +.\" +.\" 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 DEVELOPERS ``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 DEVELOPERS 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. +.\" +.Dd July 9, 2020 +.Dt SEMCTL 2 +.Os +.Sh NAME +.Nm semctl +.Nd control operations on a semaphore set +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/ipc.h +.In sys/sem.h +.Ft int +.Fn semctl "int semid" "int semnum" "int cmd" ... +.Sh DESCRIPTION +The +.Fn semctl +system call +performs the operation indicated by +.Fa cmd +on the semaphore set indicated by +.Fa semid . +A fourth argument, a +.Fa "union semun arg" , +is required for certain values of +.Fa cmd . +For the commands that use the +.Fa arg +argument, +.Fa "union semun" +must be defined as follows: +.Bd -literal +union semun { + int val; /* value for SETVAL */ + struct semid_ds *buf; /* buffer for IPC_STAT & IPC_SET */ + u_short *array; /* array for GETALL & SETALL */ +}; +.Ed +Non-portable software may define +.Dv _WANT_SEMUN +before including +.Pa sys/sem.h +to use the system definition of +.Fa "union semun" . +.Pp +Commands are performed as follows: +.\" +.\" This section based on Stevens, _Advanced Programming in the UNIX +.\" Environment_. +.\" +.Bl -tag -width IPC_RMIDXXX +.It Dv IPC_STAT +Fetch the semaphore set's +.Fa "struct semid_ds" , +storing it in the memory pointed to by +.Fa arg.buf . +.It Dv IPC_SET +Changes the +.Fa sem_perm.uid , +.Fa sem_perm.gid , +and +.Fa sem_perm.mode +members of the semaphore set's +.Fa "struct semid_ds" +to match those of the struct pointed to by +.Fa arg.buf . +The calling process's effective uid must +match either +.Fa sem_perm.uid +or +.Fa sem_perm.cuid , +or it must have superuser privileges. +.It IPC_RMID +Immediately removes the semaphore set from the system. +The calling +process's effective uid must equal the semaphore set's +.Fa sem_perm.uid +or +.Fa sem_perm.cuid , +or the process must have superuser privileges. +.It Dv GETVAL +Return the value of semaphore number +.Fa semnum . +.It Dv SETVAL +Set the value of semaphore number +.Fa semnum +to +.Fa arg.val . +Outstanding adjust on exit values for this semaphore in any process +are cleared. +.It Dv GETPID +Return the pid of the last process to perform an operation on +semaphore number +.Fa semnum . +.It Dv GETNCNT +Return the number of processes waiting for semaphore number +.Fa semnum Ns 's +value to become greater than its current value. +.It Dv GETZCNT +Return the number of processes waiting for semaphore number +.Fa semnum Ns 's +value to become 0. +.It Dv GETALL +Fetch the value of all of the semaphores in the set into the +array pointed to by +.Fa arg.array . +.It Dv SETALL +Set the values of all of the semaphores in the set to the values +in the array pointed to by +.Fa arg.array . +Outstanding adjust on exit values for all semaphores in this set, +in any process are cleared. +.El +.Pp +The +.Vt "struct semid_ds" +is defined as follows: +.\" +.\" Taken straight from <sys/sem.h>. +.\" +.Bd -literal +struct semid_ds { + struct ipc_perm sem_perm; /* operation permission struct */ + u_short sem_nsems; /* number of sems in set */ + time_t sem_otime; /* last operation time */ + time_t sem_ctime; /* last change time */ + /* Times measured in secs since */ + /* 00:00:00 GMT, Jan. 1, 1970 */ +}; +.Ed +.Sh RETURN VALUES +On success, when +.Fa cmd +is one of +.Dv GETVAL , GETPID , GETNCNT +or +.Dv GETZCNT , +.Fn semctl +returns the corresponding value; otherwise, 0 is returned. +On failure, -1 is returned, and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn semctl +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +No semaphore set corresponds to +.Fa semid . +.It Bq Er EINVAL +The +.Fa semnum +argument +is not in the range of valid semaphores for given semaphore set. +.It Bq Er EPERM +The calling process's effective uid does not match the uid of +the semaphore set's owner or creator. +.It Bq Er EACCES +Permission denied due to mismatch between operation and mode of +semaphore set. +.It Bq Er ERANGE +.Dv SETVAL +or +.Dv SETALL +attempted to set a semaphore outside the allowable range +.Bq 0 .. Dv SEMVMX . +.El +.Sh SEE ALSO +.Xr semget 2 , +.Xr semop 2 +.Sh BUGS +.Dv SETALL +may update some semaphore elements before returning an error. diff --git a/lib/libsys/semget.2 b/lib/libsys/semget.2 new file mode 100644 index 000000000000..74fcfeb13c8f --- /dev/null +++ b/lib/libsys/semget.2 @@ -0,0 +1,154 @@ +.\" +.\" Copyright (c) 1995 David Hovemeyer <daveho@infocom.com> +.\" +.\" All rights reserved. +.\" +.\" 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 DEVELOPERS ``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 DEVELOPERS 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. +.\" +.Dd March 4, 2018 +.Dt SEMGET 2 +.Os +.Sh NAME +.Nm semget +.Nd obtain a semaphore id +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/sem.h +.Ft int +.Fn semget "key_t key" "int nsems" "int flag" +.Sh DESCRIPTION +Based on the values of +.Fa key +and +.Fa flag , +.Fn semget +returns the identifier of a newly created or previously existing +set of semaphores. +.\" +.\" This is copied verbatim from the shmget manpage. Perhaps +.\" it should go in a common manpage, such as .Xr ipc 2 +.\" +The key +is analogous to a filename: it provides a handle that names an +IPC object. +There are three ways to specify a key: +.Bl -bullet +.It +IPC_PRIVATE may be specified, in which case a new IPC object +will be created. +.It +An integer constant may be specified. +If no IPC object corresponding +to +.Fa key +is specified and the IPC_CREAT bit is set in +.Fa flag , +a new one will be created. +.It +The +.Xr ftok 3 +function +may be used to generate a key from a pathname. +.El +.\" +.\" Likewise for this section, except SHM_* becomes SEM_*. +.\" +.Pp +The mode of a newly created IPC object is determined by ORing these constants +into the +.Fa flag +argument: +.Bl -tag -width 0000 +.It Dv 0400 +Read access for user. +.It Dv 0200 +Alter access for user. +.It Dv 0040 +Read access for group. +.It Dv 0020 +Alter access for group. +.It Dv 0004 +Read access for other. +.It Dv 0002 +Alter access for other. +.El +.Pp +If a new set of semaphores is being created, +.Fa nsems +is used to indicate the number of semaphores the set should contain. +Otherwise, +.Fa nsems +may be specified as 0. +.Sh RETURN VALUES +The +.Fn semget +system call +returns the id of a semaphore set if successful; otherwise, -1 +is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn semget +system call +will fail if: +.Bl -tag -width Er +.\" ipcperm could fail (we are opening to read and write, as it were) +.It Bq Er EACCES +Access permission failure. +.\" +.\" sysv_sem.c is quite explicit about these, so I'm pretty sure +.\" this is accurate +.\" +.It Bq Er EEXIST +IPC_CREAT and IPC_EXCL were specified, and a semaphore set +corresponding to +.Fa key +already exists. +.It Bq Er EINVAL +The number of semaphores requested exceeds the system imposed maximum +per set. +.It Bq Er EINVAL +A semaphore set corresponding to +.Fa key +already exists and contains fewer semaphores than +.Fa nsems . +.It Bq Er EINVAL +A semaphore set corresponding to +.Fa key +does not exist and +.Fa nsems +is 0 or negative. +.It Bq Er ENOSPC +Insufficiently many semaphores are available. +.It Bq Er ENOSPC +The kernel could not allocate a +.Fa "struct semid_ds" . +.It Bq Er ENOENT +No semaphore set was found corresponding to +.Fa key , +and IPC_CREAT was not specified. +.El +.Sh SEE ALSO +.Xr semctl 2 , +.Xr semop 2 , +.Xr ftok 3 diff --git a/lib/libsys/semop.2 b/lib/libsys/semop.2 new file mode 100644 index 000000000000..251d3909c3cd --- /dev/null +++ b/lib/libsys/semop.2 @@ -0,0 +1,287 @@ +.\" +.\" Copyright (c) 1995 David Hovemeyer <daveho@infocom.com> +.\" +.\" All rights reserved. +.\" +.\" 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 DEVELOPERS ``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 DEVELOPERS 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. +.\" +.Dd September 22, 1995 +.Dt SEMOP 2 +.Os +.Sh NAME +.Nm semop +.Nd atomic array of operations on a semaphore set +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/ipc.h +.In sys/sem.h +.Ft int +.Fn semop "int semid" "struct sembuf *array" "size_t nops" +.Sh DESCRIPTION +The +.Fn semop +system call +atomically performs the array of operations indicated by +.Fa array +on the semaphore set indicated by +.Fa semid . +The length of +.Fa array +is indicated by +.Fa nops . +Each operation is encoded in a +.Vt "struct sembuf" , +which is defined as follows: +.\" +.\" From <sys/sem.h> +.\" +.Bd -literal +struct sembuf { + u_short sem_num; /* semaphore # */ + short sem_op; /* semaphore operation */ + short sem_flg; /* operation flags */ +}; +.Ed +.Pp +For each element in +.Fa array , +.Va sem_op +and +.Va sem_flg +determine an operation to be performed on semaphore number +.Va sem_num +in the set. +The values +.Dv SEM_UNDO +and +.Dv IPC_NOWAIT +may be +.Em OR Ns 'ed +into the +.Va sem_flg +member in order to modify the behavior of the given operation. +.Pp +The operation performed depends as follows on the value of +.Va sem_op : +.\" +.\" This section is based on the description of semop() in +.\" Stevens, _Advanced Programming in the UNIX Environment_, +.\" and the semop(2) description in The Open Group Unix2 specification. +.\" +.Bl -bullet +.It +When +.Va sem_op +is positive and the process has alter permission, +the semaphore's value is incremented by +.Va sem_op Ns 's +value. +If +.Dv SEM_UNDO +is specified, the semaphore's adjust on exit value is decremented by +.Va sem_op Ns 's +value. +A positive value for +.Va sem_op +generally corresponds to a process releasing a resource +associated with the semaphore. +.It +The behavior when +.Va sem_op +is negative and the process has alter permission, +depends on the current value of the semaphore: +.Bl -bullet +.It +If the current value of the semaphore is greater than or equal to +the absolute value of +.Va sem_op , +then the value is decremented by the absolute value of +.Va sem_op . +If +.Dv SEM_UNDO +is specified, the semaphore's adjust on exit +value is incremented by the absolute value of +.Va sem_op . +.It +If the current value of the semaphore is less than the absolute value of +.Va sem_op , +one of the following happens: +.\" XXX a *second* sublist? +.Bl -bullet +.It +If +.Dv IPC_NOWAIT +was specified, then +.Fn semop +returns immediately with a return value of +.Er EAGAIN . +.It +Otherwise, the calling process is put to sleep until one of the following +conditions is satisfied: +.\" XXX We already have two sublists, why not a third? +.Bl -bullet +.It +Some other process removes the semaphore with the +.Dv IPC_RMID +option of +.Xr semctl 2 . +In this case, +.Fn semop +returns immediately with a return value of +.Er EIDRM . +.It +The process receives a signal that is to be caught. +In this case, the process will resume execution as defined by +.Xr sigaction 2 . +.It +The semaphore's +value is greater than or equal to the absolute value of +.Va sem_op . +When this condition becomes true, the semaphore's value is decremented +by the absolute value of +.Va sem_op , +the semaphore's adjust on exit value is incremented by the +absolute value of +.Va sem_op . +.El +.El +.El +.Pp +A negative value for +.Va sem_op +generally means that a process is waiting for a resource to become +available. +.It +When +.Va sem_op +is zero and the process has read permission, +one of the following will occur: +.Bl -bullet +.It +If the current value of the semaphore is equal to zero +then +.Fn semop +can return immediately. +.It +If +.Dv IPC_NOWAIT +was specified, then +.Fn semop +returns immediately with a return value of +.Er EAGAIN . +.It +Otherwise, the calling process is put to sleep until one of the following +conditions is satisfied: +.\" XXX Another nested sublists +.Bl -bullet +.It +Some other process removes the semaphore with the +.Dv IPC_RMID +option of +.Xr semctl 2 . +In this case, +.Fn semop +returns immediately with a return value of +.Er EIDRM . +.It +The process receives a signal that is to be caught. +In this case, the process will resume execution as defined by +.Xr sigaction 2 . +.It +The semaphore's value becomes zero. +.El +.El +.El +.Pp +For each semaphore a process has in use, the kernel maintains an +.Dq "adjust on exit" +value, as alluded to earlier. +When a process +exits, either voluntarily or involuntarily, the adjust on exit value +for each semaphore is added to the semaphore's value. +This can +be used to ensure that a resource is released if a process terminates +unexpectedly. +.Sh RETURN VALUES +.Rv -std semop +.Sh ERRORS +The +.Fn semop +system call will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +No semaphore set corresponds to +.Fa semid , +or the process would exceed the system-defined limit for the number of +per-process +.Dv SEM_UNDO +structures. +.It Bq Er EACCES +Permission denied due to mismatch between operation and mode of +semaphore set. +.It Bq Er EAGAIN +The semaphore's value would have resulted in the process being put to sleep +and +.Dv IPC_NOWAIT +was specified. +.It Bq Er E2BIG +Too many operations were specified. +.Bq Dv SEMOPM +.It Bq Er EFBIG +.\" +.\" I'd have thought this would be EINVAL, but the source says +.\" EFBIG. +.\" +.Va sem_num +was not in the range of valid semaphores for the set. +.It Bq Er EIDRM +The semaphore set was removed from the system. +.It Bq Er EINTR +The +.Fn semop +system call was interrupted by a signal. +.It Bq Er ENOSPC +The system +.Dv SEM_UNDO +pool +.Bq Dv SEMMNU +is full. +.It Bq Er ERANGE +The requested operation would cause either +the semaphore's current value +.Bq Dv SEMVMX +or its adjust on exit value +.Bq Dv SEMAEM +to exceed the system-imposed limits. +.El +.Sh SEE ALSO +.Xr semctl 2 , +.Xr semget 2 , +.Xr sigaction 2 +.Sh BUGS +The +.Fn semop +system call +may block waiting for memory even if +.Dv IPC_NOWAIT +was specified. diff --git a/lib/libsys/send.2 b/lib/libsys/send.2 new file mode 100644 index 000000000000..678eef139f4a --- /dev/null +++ b/lib/libsys/send.2 @@ -0,0 +1,292 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd April 27, 2020 +.Dt SEND 2 +.Os +.Sh NAME +.Nm send , +.Nm sendto , +.Nm sendmsg , +.Nm sendmmsg +.Nd send message(s) from a socket +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/socket.h +.Ft ssize_t +.Fn send "int s" "const void *msg" "size_t len" "int flags" +.Ft ssize_t +.Fn sendto "int s" "const void *msg" "size_t len" "int flags" "const struct sockaddr *to" "socklen_t tolen" +.Ft ssize_t +.Fn sendmsg "int s" "const struct msghdr *msg" "int flags" +.Ft ssize_t +.Fn sendmmsg "int s" "struct mmsghdr * restrict msgvec" "size_t vlen" "int flags" +.Sh DESCRIPTION +The +.Fn send +and +.Fn sendmmsg +functions, +and +.Fn sendto +and +.Fn sendmsg +system calls +are used to transmit one or more messages (with the +.Fn sendmmsg +call) to +another socket. +The +.Fn send +function +may be used only when the socket is in a +.Em connected +state. +The functions +.Fn sendto , +.Fn sendmsg +and +.Fn sendmmsg +may be used at any time if the socket is connectionless-mode. +If the socket is connection-mode, the protocol +must support implied connect (currently +.Xr tcp 4 +is the only protocol with support) or the socket must be in a +connected state before use. +.Pp +The address of the target is given by +.Fa to +with +.Fa tolen +specifying its size, or the equivalent +.Fa msg_name +and +.Fa msg_namelen +in +.Fa struct msghdr . +If the socket is in a connected state, the target address passed to +.Fn sendto , +.Fn sendmsg +or +.Fn sendmmsg +is ignored. +The length of the message is given by +.Fa len . +If the message is too long to pass atomically through the +underlying protocol, the error +.Er EMSGSIZE +is returned, and +the message is not transmitted. +.Pp +The +.Fn sendmmsg +function sends multiple messages at a call. +They are given by the +.Fa msgvec +vector along with +.Fa vlen +specifying the vector size. +The number of octets sent per each message is placed in the +.Fa msg_len +field of each processed element of the vector after transmission. +.Pp +No indication of failure to deliver is implicit in a +.Fn send . +Locally detected errors are indicated by a return value of -1. +.Pp +If no messages space is available at the socket to hold +the message to be transmitted, then +.Fn send +normally blocks, unless the socket has been placed in +non-blocking I/O mode. +The +.Xr select 2 +system call may be used to determine when it is possible to +send more data. +.Pp +The +.Fa flags +argument may include one or more of the following: +.Bd -literal +#define MSG_OOB 0x00001 /* process out-of-band data */ +#define MSG_DONTROUTE 0x00004 /* bypass routing, use direct interface */ +#define MSG_EOR 0x00008 /* data completes record */ +#define MSG_DONTWAIT 0x00080 /* do not block */ +#define MSG_EOF 0x00100 /* data completes transaction */ +#define MSG_NOSIGNAL 0x20000 /* do not generate SIGPIPE on EOF */ +.Ed +.Pp +The flag +.Dv MSG_OOB +is used to send +.Dq out-of-band +data on sockets that support this notion (e.g.\& +.Dv SOCK_STREAM ) ; +the underlying protocol must also support +.Dq out-of-band +data. +.Dv MSG_EOR +is used to indicate a record mark for protocols which support the +concept. +The +.Dv MSG_DONTWAIT +flag request the call to return when it would block otherwise. +.Dv MSG_EOF +requests that the sender side of a socket be shut down, and that an +appropriate indication be sent at the end of the specified data; +this flag is only implemented for +.Dv SOCK_STREAM +sockets in the +.Dv PF_INET +protocol family. +.Dv MSG_DONTROUTE +is usually used only by diagnostic or routing programs. +.Dv MSG_NOSIGNAL +is used to prevent +.Dv SIGPIPE +generation when writing a socket that +may be closed. +.Pp +See +.Xr recv 2 +for a description of the +.Fa msghdr +structure and the +.Fa mmsghdr +structure. +.Sh RETURN VALUES +The +.Fn send , +.Fn sendto +and +.Fn sendmsg +calls +return the number of octets sent. +The +.Fn sendmmsg +call returns the number of messages sent. +If an error occurred a value of -1 is returned. +.Sh ERRORS +The +.Fn send +and +.Fn sendmmsg +functions and +.Fn sendto +and +.Fn sendmsg +system calls +fail if: +.Bl -tag -width Er +.It Bq Er EBADF +An invalid descriptor was specified. +.It Bq Er EACCES +The destination address is a broadcast address, and +.Dv SO_BROADCAST +has not been set on the socket. +.It Bq Er ENOTCONN +The socket is connection-mode but is not connected. +.It Bq Er ENOTSOCK +The argument +.Fa s +is not a socket. +.It Bq Er EFAULT +An invalid user space address was specified for an argument. +.It Bq Er EMSGSIZE +The socket requires that message be sent atomically, +and the size of the message to be sent made this impossible. +.It Bq Er EAGAIN +The socket is marked non-blocking, or +.Dv MSG_DONTWAIT +is specified, and the requested operation would block. +.It Bq Er ENOBUFS +The system was unable to allocate an internal buffer. +The operation may succeed when buffers become available. +.It Bq Er 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. +.It Bq Er EHOSTUNREACH +The remote host was unreachable. +.It Bq Er EISCONN +A destination address was specified and the socket is already connected. +.It Bq Er ECONNREFUSED +The socket received an ICMP destination unreachable message +from the last message sent. +This typically means that the +receiver is not listening on the remote port. +.It Bq Er EHOSTDOWN +The remote host was down. +.It Bq Er ENETDOWN +The remote network was down. +.It Bq Er EADDRNOTAVAIL +The process using a +.Dv SOCK_RAW +socket was jailed and the source +address specified in the IP header did not match the IP +address bound to the prison. +.It Bq Er EPIPE +The socket is unable to send anymore data +.Dv ( SBS_CANTSENDMORE +has been set on the socket). +This typically means that the socket +is not connected. +.El +.Sh SEE ALSO +.Xr connect 2 , +.Xr fcntl 2 , +.Xr getsockopt 2 , +.Xr recv 2 , +.Xr select 2 , +.Xr socket 2 , +.Xr write 2 , +.Xr CMSG_DATA 3 +.Sh HISTORY +The +.Fn send +function appeared in +.Bx 4.2 . +The +.Fn sendmmsg +function appeared in +.Fx 11.0 . +.Sh BUGS +Because +.Fn sendmsg +does not necessarily block until the data has been transferred, it +is possible to transfer an open file descriptor across an +.Dv AF_UNIX +domain socket +(see +.Xr recv 2 ) , +then +.Fn close +it before it has actually been sent, the result being that the receiver +gets a closed file descriptor. +It is left to the application to +implement an acknowledgment mechanism to prevent this from happening. diff --git a/lib/libsys/sendfile.2 b/lib/libsys/sendfile.2 new file mode 100644 index 000000000000..6000e3e9828f --- /dev/null +++ b/lib/libsys/sendfile.2 @@ -0,0 +1,437 @@ +.\" Copyright (c) 2003, David G. Lawrence +.\" All rights reserved. +.\" +.\" 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 unmodified, 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. +.\" +.Dd June 24, 2025 +.Dt SENDFILE 2 +.Os +.Sh NAME +.Nm sendfile +.Nd send a file to a socket +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In sys/uio.h +.Ft int +.Fo sendfile +.Fa "int fd" "int s" "off_t offset" "size_t nbytes" +.Fa "struct sf_hdtr *hdtr" "off_t *sbytes" "int flags" +.Fc +.Sh DESCRIPTION +The +.Fn sendfile +system call +sends a regular file or shared memory object specified by descriptor +.Fa fd +out a stream socket specified by descriptor +.Fa s . +.Pp +The +.Fa offset +argument specifies where to begin in the file. +Should +.Fa offset +fall beyond the end of file, the system will return +success and report 0 bytes sent as described below. +The +.Fa nbytes +argument specifies how many bytes of the file should be sent, with 0 having the special +meaning of send until the end of file has been reached. +.Pp +An optional header and/or trailer can be sent before and after the file data by specifying +a pointer to a +.Vt "struct sf_hdtr" , +which has the following structure: +.Pp +.Bd -literal -offset indent -compact +struct sf_hdtr { + struct iovec *headers; /* pointer to header iovecs */ + int hdr_cnt; /* number of header iovecs */ + struct iovec *trailers; /* pointer to trailer iovecs */ + int trl_cnt; /* number of trailer iovecs */ +}; +.Ed +.Pp +The +.Fa headers +and +.Fa trailers +pointers, if +.Pf non- Dv NULL , +point to arrays of +.Vt "struct iovec" +structures. +See the +.Fn writev +system call for information on the iovec structure. +The number of iovecs in these +arrays is specified by +.Fa hdr_cnt +and +.Fa trl_cnt . +.Pp +If +.Pf non- Dv NULL , +the system will write the total number of bytes sent on the socket to the +variable pointed to by +.Fa sbytes . +.Pp +The least significant 16 bits of +.Fa flags +argument is a bitmap of these values: +.Bl -tag -offset indent -width "SF_USER_READAHEAD" +.It Dv SF_NODISKIO +This flag causes +.Nm +to return +.Er EBUSY +instead of blocking when a busy page is encountered. +This rare situation can happen if some other process is now working +with the same region of the file. +It is advised to retry the operation after a short period. +.Pp +Note that in older +.Fx +versions the +.Dv SF_NODISKIO +had slightly different notion. +The flag prevented +.Nm +to run I/O operations in case if an invalid (not cached) page is encountered, +thus avoiding blocking on I/O. +Starting with +.Fx 11 +.Nm +sending files off the +.Xr ffs 4 +filesystem does not block on I/O +(see +.Sx IMPLEMENTATION NOTES +), so the condition no longer applies. +However, it is safe if an application utilizes +.Dv SF_NODISKIO +and on +.Er EBUSY +performs the same action as it did in +older +.Fx +versions, e.g., +.Xr aio_read 2 , +.Xr read 2 +or +.Nm +in a different context. +.It Dv SF_NOCACHE +The data sent to socket will not be cached by the virtual memory system, +and will be freed directly to the pool of free pages. +.It Dv SF_USER_READAHEAD +.Nm +has some internal heuristics to do readahead when sending data. +This flag forces +.Nm +to override any heuristically calculated readahead and use exactly the +application specified readahead. +See +.Sx SETTING READAHEAD +for more details on readahead. +.El +.Pp +When using a socket marked for non-blocking I/O, +.Fn sendfile +may send fewer bytes than requested. +In this case, the number of bytes successfully +written is returned in +.Fa *sbytes +(if specified), +and the error +.Er EAGAIN +is returned. +.Sh SETTING READAHEAD +.Nm +uses internal heuristics based on request size and file system layout +to do readahead. +Additionally application may request extra readahead. +The most significant 16 bits of +.Fa flags +specify amount of pages that +.Nm +may read ahead when reading the file. +A macro +.Fn SF_FLAGS +is provided to combine readahead amount and flags. +An example showing specifying readahead of 16 pages and +.Dv SF_NOCACHE +flag: +.Pp +.Bd -literal -offset indent -compact + SF_FLAGS(16, SF_NOCACHE) +.Ed +.Pp +.Nm +will use either application specified readahead or internally calculated, +whichever is bigger. +Setting flag +.Dv SF_USER_READAHEAD +would turn off any heuristics and set maximum possible readahead length to +the number of pages specified via flags. +.Sh IMPLEMENTATION NOTES +The +.Fx +implementation of +.Fn sendfile +does not block on disk I/O when it sends a file off the +.Xr ffs 4 +filesystem. +The syscall returns success before the actual I/O completes, and data +is put into the socket later unattended. +However, the order of data in the socket is preserved, so it is safe +to do further writes to the socket. +.Pp +The +.Fx +implementation of +.Fn sendfile +is "zero-copy", meaning that it has been optimized so that copying of the file data is avoided. +.Sh TUNING +.Ss physical paging buffers +.Fn sendfile +uses vnode pager to read file pages into memory. +The pager uses a pool of physical buffers to run its I/O operations. +When system runs out of pbufs, sendfile will block and report state +.Dq Li zonelimit . +Size of the pool can be tuned with +.Va vm.vnode_pbufs +.Xr loader.conf 5 +tunable and can be checked with +.Xr sysctl 8 +OID of the same name at runtime. +.Ss sendfile(2) buffers +On some architectures, this system call internally uses a special +.Fn sendfile +buffer +.Pq Vt "struct sf_buf" +to handle sending file data to the client. +If the sending socket is +blocking, and there are not enough +.Fn sendfile +buffers available, +.Fn sendfile +will block and report a state of +.Dq Li sfbufa . +If the sending socket is non-blocking and there are not enough +.Fn sendfile +buffers available, the call will block and wait for the +necessary buffers to become available before finishing the call. +.Pp +The number of +.Vt sf_buf Ns 's +allocated should be proportional to the number of nmbclusters used to +send data to a client via +.Fn sendfile . +Tune accordingly to avoid blocking! +Busy installations that make extensive use of +.Fn sendfile +may want to increase these values to be inline with their +.Va kern.ipc.nmbclusters +(see +.Xr tuning 7 +for details). +.Pp +The number of +.Fn sendfile +buffers available is determined at boot time by either the +.Va kern.ipc.nsfbufs +.Xr loader.conf 5 +variable or the +.Dv NSFBUFS +kernel configuration tunable. +The number of +.Fn sendfile +buffers scales with +.Va kern.maxusers . +The +.Va kern.ipc.nsfbufsused +and +.Va kern.ipc.nsfbufspeak +read-only +.Xr sysctl 8 +variables show current and peak +.Fn sendfile +buffers usage respectively. +These values may also be viewed through +.Nm netstat Fl m . +.Pp +If +.Xr sysctl 8 +OID +.Va kern.ipc.nsfbufs +doesn't exist, your architecture does not need to use +.Fn sendfile +buffers because their task can be efficiently performed +by the generic virtual memory structures. +.Sh RETURN VALUES +.Rv -std sendfile +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EAGAIN +The socket is marked for non-blocking I/O and not all data was sent due to +the socket buffer being filled. +If specified, the number of bytes successfully sent will be returned in +.Fa *sbytes . +.It Bq Er EBADF +The +.Fa fd +argument +is not a valid file descriptor. +.It Bq Er EBADF +The +.Fa s +argument +is not a valid socket descriptor. +.It Bq Er EBUSY +A busy page was encountered and +.Dv SF_NODISKIO +had been specified. +Partial data may have been sent. +.It Bq Er EFAULT +An invalid address was specified for an argument. +.It Bq Er EINTR +A signal interrupted +.Fn sendfile +before it could be completed. +If specified, the number +of bytes successfully sent will be returned in +.Fa *sbytes . +.It Bq Er EINVAL +The +.Fa fd +argument +is not a regular file. +.It Bq Er EINVAL +The +.Fa s +argument +is not a SOCK_STREAM type socket. +.It Bq Er EINVAL +The +.Fa offset +argument +is negative. +.It Bq Er EIO +An error occurred while reading from +.Fa fd . +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from +.Fa fd . +.It Bq Er ENOTCAPABLE +The +.Fa fd +or the +.Fa s +argument has insufficient rights. +.It Bq Er ENOBUFS +The system was unable to allocate an internal buffer. +.It Bq Er ENOTCONN +The +.Fa s +argument +points to an unconnected socket. +.It Bq Er ENOTSOCK +The +.Fa s +argument +is not a socket. +.It Bq Er EOPNOTSUPP +The file system for descriptor +.Fa fd +does not support +.Fn sendfile . +.It Bq Er EPIPE +The socket peer has closed the connection. +.El +.Sh SEE ALSO +.Xr netstat 1 , +.Xr open 2 , +.Xr send 2 , +.Xr socket 2 , +.Xr writev 2 , +.Xr loader.conf 5 , +.Xr tuning 7 , +.Xr sysctl 8 +.Rs +.%A K. Elmeleegy +.%A A. Chanda +.%A A. L. Cox +.%A W. Zwaenepoel +.%T A Portable Kernel Abstraction for Low-Overhead Ephemeral Mapping Management +.%J The Proceedings of the 2005 USENIX Annual Technical Conference +.%P pp 223-236 +.%D 2005 +.Re +.Sh HISTORY +The +.Fn sendfile +system call +first appeared in +.Fx 3.0 . +This manual page first appeared in +.Fx 3.1 . +In +.Fx 10 +support for sending shared memory descriptors had been introduced. +In +.Fx 11 +a non-blocking implementation had been introduced. +.Sh AUTHORS +The initial implementation of +.Fn sendfile +system call +and this manual page were written by +.An David G. Lawrence Aq Mt dg@dglawrence.com . +The +.Fx 11 +implementation was written by +.An Gleb Smirnoff Aq Mt glebius@FreeBSD.org . +.Sh BUGS +The +.Fn sendfile +system call will not fail, i.e., return +.Dv -1 +and set +.Va errno +to +.Er EFAULT , +if provided an invalid address for +.Fa sbytes . +The +.Fn sendfile +system call does not support SCTP sockets, +it will return +.Dv -1 +and set +.Va errno +to +.Er EINVAL . diff --git a/lib/libsys/sendmmsg.c b/lib/libsys/sendmmsg.c new file mode 100644 index 000000000000..41eb62d1e0c8 --- /dev/null +++ b/lib/libsys/sendmmsg.c @@ -0,0 +1,61 @@ +/* + * Copyright (c) 2016 Boris Astardzhiev, Smartcom-Bulgaria AD + * All rights reserved. + * + * 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(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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. + */ + +#include <sys/types.h> +#include <sys/socket.h> +#include "libc_private.h" + +ssize_t +sendmmsg(int s, struct mmsghdr *__restrict msgvec, size_t vlen, int flags) +{ + size_t i, sent; + ssize_t ret; + + sent = 0; + for (i = 0; i < vlen; i++, sent++) { + ret = __sys_sendmsg(s, &msgvec[i].msg_hdr, flags); + if (ret == -1) { + if (sent != 0) { + /* + * We have sent messages. Let caller + * know about the data sent, socket + * error is returned on next + * invocation. + */ + return (sent); + } + return (ret); + } + + /* Save sent bytes. */ + msgvec[i].msg_len = ret; + } + + return (sent); +} diff --git a/lib/libsys/setcred.2 b/lib/libsys/setcred.2 new file mode 100644 index 000000000000..86f61ddfdb30 --- /dev/null +++ b/lib/libsys/setcred.2 @@ -0,0 +1,290 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright © 2024 The FreeBSD Foundation +.\" +.\" This documentation was written by Olivier Certner <olce.freebsd@certner.fr> +.\" at Kumacom SARL under sponsorship from the FreeBSD Foundation. +.\" +.Dd December 19, 2024 +.Dt SETCRED 2 +.Os +.Sh NAME +.Nm setcred +.Nd set current process credentials atomically +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/ucred.h +.Ft int +.Fn setcred "u_int flags" "const struct setcred *wcred" "size_t size" +.Sh DESCRIPTION +The +.Fn setcred +system call can set any combination of user-accessible credentials of the +current process in an atomic manner. +.Pp +This system call is normally permitted only for processes having the ID of the +super-user (0) as their effective user ID, or not at all if the +.Xr sysctl 8 +variable +.Va security.bsd.suser_enabled +is zero or some active MAC policy specifically denies these processes. +.Pp +Some MAC policies, such as +.Xr mac_do 4 , +may also allow unprivileged users to call it successfully, possibly depending on +the exact credentials transition requested, once again unless any active MAC +policy specifically denies that. +.Pp +The +.Fa flags +argument serves to indicate which process credentials should be changed by the +call. +Allowed flags are: +.Pp +.Bl -tag -width "SETCREDF_SUPP_GROUPS " -compact +.It Fa SETCREDF_UID +Set the effective user ID. +.It Fa SETCREDF_RUID +Set the real user ID. +.It Fa SETCREDF_SVUID +Set the saved user ID. +.It Fa SETCREDF_GID +Set the effective group ID. +.It Fa SETCREDF_RGID +Set the real group ID. +.It Fa SETCREDF_SVGID +Set the saved group ID. +.It Fa SETCREDF_SUPP_GROUPS +Set the supplementary group list. +.It Fa SETCREDF_MAC_LABEL +Set the MAC label. +.El +.Pp +The +.Vt struct setcred +structure is currently defined as: +.Bd -literal +struct setcred { + uid_t sc_uid; /* effective user id */ + uid_t sc_ruid; /* real user id */ + uid_t sc_svuid; /* saved user id */ + gid_t sc_gid; /* effective group id */ + gid_t sc_rgid; /* real group id */ + gid_t sc_svgid; /* saved group id */ + u_int sc_pad; /* padding, unused */ + u_int sc_supp_groups_nb; /* supplementary groups number */ + gid_t *sc_supp_groups; /* supplementary groups */ + struct mac *sc_label; /* MAC label */ +}; +.Ed +.Pp +Its fields are: +.Pp +.Bl -tag -width "sc_supp_groups_nb " -compact +.It Fa sc_uid +The ID to set the effective user to, if flag +.Dv SETCREDF_UID +is specified. +.It Fa sc_ruid +The ID to set the real user to, if flag +.Dv SETCREDF_RUID +is specified. +.It Fa sc_svuid +The ID to set the saved user to, if flag +.Dv SETCREDF_SVUID +is specified. +.It Fa sc_gid +The ID to set the effective group to, if flag +.Dv SETCREDF_GID +is specified. +.It Fa sc_rgid +The ID to set the real group to, if flag +.Dv SETCREDF_RGID +is specified. +.It Fa sc_svgid +The ID to set the saved group to, if flag +.Dv SETCREDF_SVGID +is specified. +.It Fa sc_supp_groups_nb +The size of array +.Fa sc_supp_groups , +if flag +.Dv SETCREDF_SUPP_GROUPS +is specified. +It must be less than or equal to +.Dv {NGROUPS_MAX} . +.It Fa sc_supp_groups +An array of IDs to set the supplementary groups to, if flag +.Dv SETCREDF_SUPP_GROUPS +is specified. +Note that all groups in this array will be set as supplementary groups only, in +contrast to +.Xr setgroups 2 +which treats the first element specially as the new effective group, not adding +it to supplementary groups. +.It Fa sc_label +A pointer to a valid MAC label structure, e.g., built with the +.Xr mac_from_text 3 +function, if flag +.Dv SETCREDF_MAC_LABEL +is specified. +.El +.Pp +For forward compatibility and security reasons, it is recommended that users +always initialize objects of type +.Vt struct setcred +with the provided initializer: +.Dv SETCRED_INITIALIZER . +.Pp +The +.Fa size +argument must be the size of the passed +.Fa wcred +structure. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn setcred +system call will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Unrecognized flags were passed in +.Fa flags , +or the +.Fa size +parameter does not match the size of +.Vt struct setcred , +or the field +.Fa sc_supp_group_nb +has a value strictly greater than +.Dv {NGROUPS_MAX} +.Po if flag +.Dv SETCREDF_SUPP_GROUPS +was supplied +.Pc , +or the MAC label pointed to by field +.Fa sc_label +is invalid +.Po if flag +.Dv SETCREDF_MAC_LABEL +was supplied +.Pc . +.It Bq Er EFAULT +The +.Fa wcred +pointer, or pointers in fields +.Fa sc_supp_groups +.Po if flag +.Dv SETCREDF_SUPP_GROUPS +was supplied +.Pc +or +.Fa sc_label +.Po if flag +.Dv SETCREDF_MAC_LABEL +was supplied +.Pc +point to invalid locations. +.It Bq Er EPERM +The user is not the super-user and/or the requested credentials transition is +not allowed by the system or MAC modules. +.It Bq Er EOPNOTSUPP +Some of the requested credentials have a type that the system does not support. +This currently can occur only if the kernel has been compiled without MAC and +.Dv SETCREDF_MAC_LABEL +has been passed. +.El +.Sh SEE ALSO +.Xr issetugid 2 , +.Xr setregid 2 , +.Xr setreuid 2 , +.Xr setuid 2 , +.Xr mac_text 3 , +.Xr mac 4 , +.Xr mac_do 4 , +.Xr maclabel 7 +.Sh STANDARDS +The +.Fn setcred +system call is specific to +.Fx . +.Pp +A call to +.Fn setcred +usually changes process credentials that are listed by POSIX/SUS standards. +The changed values then produce the effects with respect to the rest of the +system that are described in these standards, as if these changes had resulted +from calling standard or traditional credentials-setting functions. +Currently, all flags but +.Dv SETCREDF_MAC_LABEL +lead to modifying standard credentials. +.Pp +The only differences in using +.Fn setcred +to change standard credentials instead of standard or traditional functions are: +.Pp +.Bl -bullet -compact +.It +All requested changes are performed atomically. +.It +Only the super-user or an unprivileged user authorized by some MAC module can +successfully call +.Fn setcred , +even if the standard system calls would have authorized any unprivileged user to +effect the same changes. +For example, +.Fn seteuid +allows any unprivileged user to change the effective user ID to either the real +or saved ones, while +.Fn setcred +called with flag +.Dv SETCREDF_UID +does not. +.El +.Sh HISTORY +The +.Fn setcred +system call appeared in +.Fx 14.3 . +.Pp +Traditionally in UNIX, all credential changes beyond shuffles of effective, real +and saved IDs have been done by setuid binaries that successively call multiple +credentials-setting system calls and in a specific order. +For example, to change all user IDs to that of some unprivileged user, +.Fn setuid +must be called last so that all other credentials-changing calls can be +performed successfully beforehand, as they require super-user privileges. +.Pp +This piecewise approach causes such a process to transiently hold high privilege +credentials that are neither the original nor necessarily the desired final +ones. +Besides opening a transition window where possible vulnerabilities could have +catastrophic consequences, it makes it impossible for the kernel to enforce that +only certain transitions of credentials are allowed. +.Pp +The necessity of an atomic, global approach to changing credentials clearly +appeared while working on extending +.Xr mac_do 4 +to allow rules to authorize only specific changes of primary or supplementary +groups, which prompted the addition of +.Fn setcred . +.Sh AUTHORS +The +.Fn setcred +system call and this manual page were written by +.An Olivier Certner Aq Mt olce.freebsd@certner.fr . +.Sh SECURITY CONSIDERATIONS +The same considerations as those of standard or traditional credentials-setting +system calls apply to +.Fn setcred , +except for the lack of atomicity of successive such calls. +.Pp +In particular, please consult section +.Sy SECURITY CONSIDERATIONS +of the +.Xr setuid 2 +manual page about the absence of effect of changing standard credentials on +already open files. diff --git a/lib/libsys/setfib.2 b/lib/libsys/setfib.2 new file mode 100644 index 000000000000..57e83c0d1adb --- /dev/null +++ b/lib/libsys/setfib.2 @@ -0,0 +1,110 @@ +.\" Copyright (c) 2008 Cisco Systems. All rights reserved. +.\" Author: Julian Elischer +.\" +.\" 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. Neither the name of the Cisco Systems nor the names of its employees +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``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 AUTHORS 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. +.\" +.Dd January 10, 2025 +.Dt SETFIB 2 +.Os +.Sh NAME +.Nm setfib +.Nd set the default FIB (routing table) for the calling process +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/socket.h +.Ft int +.Fn setfib "int fib" +.Sh DESCRIPTION +The +.Fn setfib +system call sets the associated FIB (routing table) for all sockets opened +subsequent to the call, to be that of the argument +.Fa fib . +The +.Fa fib +argument +must be greater than or equal to 0 +and less than the current system maximum which +may be retrieved by the +.Va net.fibs +sysctl. +The system maximum is set in the kernel configuration file with +.Bd -ragged -offset indent +.Cd "options ROUTETABLES=" Ns Em N +.Ed +.Pp +or in +.Pa /boot/loader.conf +or +.Pa /etc/sysctl.conf +with +.Pp +.Dl net.fibs= Ns Qq Em N +.Pp +where +.Em N +is an integer smaller than 65536. +Note that the number of FIBs may be increased after booting, but cannot be +reduced. +.Pp +The maximum of 65536 is due to the implementation storing +the FIB number in a 16-bit field in the +.Xr mbuf 9 +packet header, however it is not suggested that one use such a large number +as memory is allocated for every FIB regardless of whether it is used, and +there are places where all FIBs are iterated over. +.Pp +The default FIB of the process will be applied to all protocol families +that support multiple FIBs, and ignored by those that do not. +The default FIB for a process may be overridden for a socket with the use +of the +.Dv SO_SETFIB +socket option. +.Sh RETURN VALUES +.Rv -std setfib +.Sh ERRORS +The +.Fn setfib +system call +will fail and no action will be taken and return +.Er EINVAL +if the +.Fa fib +argument is greater than the current system maximum. +.Sh SEE ALSO +.Xr setfib 1 , +.Xr setsockopt 2 +.Sh STANDARDS +The +.Fn setfib +system call is a +.Fx +extension however similar extensions +have been added to many other +.Ux +style kernels. +.Sh HISTORY +The +.Fn setfib +function appeared in +.Fx 7.1 . diff --git a/lib/libsys/setgroups.2 b/lib/libsys/setgroups.2 new file mode 100644 index 000000000000..a226aeafea96 --- /dev/null +++ b/lib/libsys/setgroups.2 @@ -0,0 +1,101 @@ +.\" Copyright (c) 1983, 1991, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd January 19, 2018 +.Dt SETGROUPS 2 +.Os +.Sh NAME +.Nm setgroups +.Nd set group access list +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In unistd.h +.Ft int +.Fn setgroups "int ngroups" "const gid_t *gidset" +.Sh DESCRIPTION +The +.Fn setgroups +system call +sets the group access list of the current user process +according to the array +.Fa gidset . +The +.Fa ngroups +argument +indicates the number of entries in the array and must be no +more than +.Dv {NGROUPS_MAX}+1 . +.Pp +Only the super-user may set a new group list. +.Pp +The first entry of the group array +.Pq Va gidset[0] +is used as the effective group-ID for the process. +This entry is over-written when a setgid program is run. +To avoid losing access to the privileges of the +.Va gidset[0] +entry, it should be duplicated later in the group array. +By convention, +this happens because the group value indicated +in the password file also appears in +.Pa /etc/group . +The group value in the password file is placed in +.Va gidset[0] +and that value then gets added a second time when the +.Pa /etc/group +file is scanned to create the group set. +.Sh RETURN VALUES +.Rv -std setgroups +.Sh ERRORS +The +.Fn setgroups +system call will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +The caller is not the super-user. +.It Bq Er EINVAL +The number specified in the +.Fa ngroups +argument is larger than the +.Dv {NGROUPS_MAX}+1 +limit. +.It Bq Er EFAULT +The address specified for +.Fa gidset +is outside the process +address space. +.El +.Sh SEE ALSO +.Xr getgroups 2 , +.Xr initgroups 3 +.Sh HISTORY +The +.Fn setgroups +system call appeared in +.Bx 4.2 . diff --git a/lib/libsys/setpgid.2 b/lib/libsys/setpgid.2 new file mode 100644 index 000000000000..1c0a6ae02727 --- /dev/null +++ b/lib/libsys/setpgid.2 @@ -0,0 +1,107 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd February 8, 2004 +.Dt SETPGID 2 +.Os +.Sh NAME +.Nm setpgid , +.Nm setpgrp +.Nd set process group +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn setpgid "pid_t pid" "pid_t pgrp" +.Ft int +.Fn setpgrp "pid_t pid" "pid_t pgrp" +.Sh DESCRIPTION +The +.Fn setpgid +system call +sets the process group of the specified process +.Fa pid +to the specified +.Fa pgrp . +If +.Fa pid +is zero, then the call applies to the current process. +If +.Fa pgrp +is zero, then the process id of the process specified by +.Fa pid +is used instead. +.Pp +If the affected process is not the invoking process, then it must be a +child of the invoking process, it must not have performed an +.Xr exec 3 +operation, and both processes must be in the same session. +The requested process group ID must already exist in the session of +the caller, or it must be equal to the target process ID. +.Sh RETURN VALUES +.Rv -std setpgid +.Sh COMPATIBILITY +The +.Fn setpgrp +system call +is identical to +.Fn setpgid , +and is retained for calling convention compatibility with historical +versions of +.Bx . +.Sh ERRORS +The +.Fn setpgid +system call +will fail and the process group will not be altered if: +.Bl -tag -width Er +.It Bq Er EINVAL +The requested process group ID is not legal. +.It Bq Er ESRCH +The requested process does not exist. +.It Bq Er ESRCH +The target process is not the calling process or +a child of the calling process. +.It Bq Er EACCES +The requested process is a child of the calling process, +but it has performed an +.Xr exec 3 +operation. +.It Bq Er EPERM +The target process is a session leader. +.It Bq Er EPERM +The requested process group ID is not in the session of the caller, +and it is not equal to the process ID of the target process. +.El +.Sh SEE ALSO +.Xr getpgrp 2 +.Sh STANDARDS +The +.Fn setpgid +system call is expected to conform to +.St -p1003.1-90 . diff --git a/lib/libsys/setregid.2 b/lib/libsys/setregid.2 new file mode 100644 index 000000000000..f340fb4edb30 --- /dev/null +++ b/lib/libsys/setregid.2 @@ -0,0 +1,87 @@ +.\" Copyright (c) 1980, 1991, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd April 16, 1994 +.Dt SETREGID 2 +.Os +.Sh NAME +.Nm setregid +.Nd set real and effective group ID +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn setregid "gid_t rgid" "gid_t egid" +.Sh DESCRIPTION +The real and effective group ID's of the current process +are set to the arguments. +If the real group ID is changed, the saved group ID is changed to the +new value of the effective group ID. +.Pp +Unprivileged users may change the real group +ID to the effective group ID and vice-versa; only the super-user may +make other changes. +.Pp +Supplying a value of -1 for either the real or effective +group ID forces the system to substitute the current +ID in place of the -1 argument. +.Pp +The +.Fn setregid +system call was intended to allow swapping +the real and effective group IDs +in set-group-ID programs to temporarily relinquish the set-group-ID value. +This system call did not work correctly, +and its purpose is now better served by the use of the +.Xr setegid 2 +system call. +.Pp +When setting the real and effective group IDs to the same value, +the standard +.Fn setgid +system call is preferred. +.Sh RETURN VALUES +.Rv -std setregid +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EPERM +The current process is not the super-user and a change +other than changing the effective group-id to the real group-id +was specified. +.El +.Sh SEE ALSO +.Xr getgid 2 , +.Xr issetugid 2 , +.Xr setegid 2 , +.Xr setgid 2 , +.Xr setuid 2 +.Sh HISTORY +The +.Fn setregid +system call appeared in +.Bx 4.2 . diff --git a/lib/libsys/setresuid.2 b/lib/libsys/setresuid.2 new file mode 100644 index 000000000000..28038dec6637 --- /dev/null +++ b/lib/libsys/setresuid.2 @@ -0,0 +1,92 @@ +.\" Copyright (c) 2000 +.\" Sheldon Hearn. All rights reserved. +.\" +.\" 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 +.\" +.Dd February 7, 2015 +.Dt SETRESUID 2 +.Os +.Sh NAME +.Nm getresgid , +.Nm getresuid , +.Nm setresgid , +.Nm setresuid +.Nd "get or set real, effective and saved user or group ID" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In unistd.h +.Ft int +.Fn getresgid "gid_t *rgid" "gid_t *egid" "gid_t *sgid" +.Ft int +.Fn getresuid "uid_t *ruid" "uid_t *euid" "uid_t *suid" +.Ft int +.Fn setresgid "gid_t rgid" "gid_t egid" "gid_t sgid" +.Ft int +.Fn setresuid "uid_t ruid" "uid_t euid" "uid_t suid" +.Sh DESCRIPTION +The +.Fn setresuid +system call sets the real, +effective and saved user IDs of the current process. +The analogous +.Fn setresgid +sets the real, effective and saved group IDs. +.Pp +Privileged processes may set these IDs +to arbitrary values. +Unprivileged processes are restricted +in that each of the new IDs must match one of the current IDs. +.Pp +Passing -1 as an argument causes the corresponding value +to remain unchanged. +.Pp +The +.Fn getresgid +and +.Fn getresuid +calls retrieve the real, effective, and saved group and user IDs of +the current process, respectively. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EPERM +The calling process was not privileged +and tried to change one or more IDs to a value +which was not the current real ID, the current effective ID +nor the current saved ID. +.It Bq Er EFAULT +An address passed to +.Fn getresgid +or +.Fn getresuid +was invalid. +.El +.Sh SEE ALSO +.Xr getegid 2 , +.Xr geteuid 2 , +.Xr getgid 2 , +.Xr getuid 2 , +.Xr issetugid 2 , +.Xr setgid 2 , +.Xr setregid 2 , +.Xr setreuid 2 , +.Xr setuid 2 +.Sh HISTORY +These functions first appeared in HP-UX. diff --git a/lib/libsys/setreuid.2 b/lib/libsys/setreuid.2 new file mode 100644 index 000000000000..cdd55560f7cb --- /dev/null +++ b/lib/libsys/setreuid.2 @@ -0,0 +1,87 @@ +.\" Copyright (c) 1980, 1991, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd February 8, 2001 +.Dt SETREUID 2 +.Os +.Sh NAME +.Nm setreuid +.Nd set real and effective user ID's +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn setreuid "uid_t ruid" "uid_t euid" +.Sh DESCRIPTION +The real and effective user IDs of the +current process are set according to the arguments. +If +.Fa ruid +or +.Fa euid +is -1, the current uid is filled in by the system. +Unprivileged users may change the real user +ID to the effective user ID and vice-versa; only the super-user may +make other changes. +.Pp +If the real user ID is changed (i.e.\& +.Fa ruid +is not -1) or the effective user ID is changed to something other than +the real user ID, then the saved user ID will be set to the effective user ID. +.Pp +The +.Fn setreuid +system call has been used to swap the real and effective user IDs +in set-user-ID programs to temporarily relinquish the set-user-ID value. +This purpose is now better served by the use of the +.Xr seteuid 2 +system call. +.Pp +When setting the real and effective user IDs to the same value, +the standard +.Fn setuid +system call is preferred. +.Sh RETURN VALUES +.Rv -std setreuid +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EPERM +The current process is not the super-user and a change +other than changing the effective user-id to the real user-id +was specified. +.El +.Sh SEE ALSO +.Xr getuid 2 , +.Xr issetugid 2 , +.Xr seteuid 2 , +.Xr setuid 2 +.Sh HISTORY +The +.Fn setreuid +system call appeared in +.Bx 4.2 . diff --git a/lib/libsys/setsid.2 b/lib/libsys/setsid.2 new file mode 100644 index 000000000000..3484ef069460 --- /dev/null +++ b/lib/libsys/setsid.2 @@ -0,0 +1,78 @@ +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd June 4, 1993 +.Dt SETSID 2 +.Os +.Sh NAME +.Nm setsid +.Nd create session and set process group ID +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft pid_t +.Fn setsid void +.Sh DESCRIPTION +The +.Fn setsid +system call creates a new session. +The calling process is the session leader of the new session, is the +process group leader of a new process group and has no controlling +terminal. +The calling process is the only process in either the session or the +process group. +.Sh RETURN VALUES +Upon successful completion, the +.Fn setsid +system call returns the value of the process group ID of the new process +group, which is the same as the process ID of the calling process. +If an error occurs, +.Fn setsid +returns -1 and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn setsid +system call will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +The calling process is already a process group leader, or the process +group ID of a process other than the calling process matches the process +ID of the calling process. +.El +.Sh SEE ALSO +.Xr setpgid 2 , +.Xr tcgetpgrp 3 , +.Xr tcsetpgrp 3 +.Sh STANDARDS +The +.Fn setsid +system call is expected to be compliant with the +.St -p1003.1-90 +specification. diff --git a/lib/libsys/setuid.2 b/lib/libsys/setuid.2 new file mode 100644 index 000000000000..49919b9c328c --- /dev/null +++ b/lib/libsys/setuid.2 @@ -0,0 +1,186 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd December 15, 2015 +.Dt SETUID 2 +.Os +.Sh NAME +.Nm setuid , +.Nm seteuid , +.Nm setgid , +.Nm setegid +.Nd set user and group ID +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn setuid "uid_t uid" +.Ft int +.Fn seteuid "uid_t euid" +.Ft int +.Fn setgid "gid_t gid" +.Ft int +.Fn setegid "gid_t egid" +.Sh DESCRIPTION +The +.Fn setuid +system call +sets the real and effective +user IDs and the saved set-user-ID of the current process +to the specified value. +.\" Comment out next block for !_POSIX_SAVED_IDS +.\" The real user ID and the saved set-user-ID are changed only if the +.\" effective user ID is that of the super user. +.\" I.e. +.\" .Fn setuid +.\" system call is equal to +.\" .Fn seteuid +.\" system call if the effective user ID is not that of the super user. +.\" End of block +The +.Fn setuid +system call is permitted if the specified ID is equal to the real user ID +.\" Comment out next line for !_POSIX_SAVED_IDS +.\" or the saved set-user-ID +.\" Next line is for Appendix B.4.2.2 case. +or the effective user ID +of the process, or if the effective user ID is that of the super user. +.Pp +The +.Fn setgid +system call +sets the real and effective +group IDs and the saved set-group-ID of the current process +to the specified value. +.\" Comment out next block for !_POSIX_SAVED_IDS +.\" The real group ID and the saved set-group-ID are changed only if the +.\" effective user ID is that of the super user. +.\" I.e. +.\" .Fn setgid +.\" system call is equal to +.\" .Fn setegid +.\" system call if the effective user ID is not that of the super user. +.\" End of block +The +.Fn setgid +system call is permitted if the specified ID is equal to the real group ID +.\" Comment out next line for !_POSIX_SAVED_IDS +.\" or the saved set-group-ID +.\" Next line is for Appendix B.4.2.2 case. +or the effective group ID +of the process, or if the effective user ID is that of the super user. +.Pp +The +.Fn seteuid +system call +.Pq Fn setegid +sets the effective user ID (group ID) of the +current process. +The effective user ID may be set to the value +of the real user ID or the saved set-user-ID (see +.Xr intro 2 +and +.Xr execve 2 ) ; +in this way, the effective user ID of a set-user-ID executable +may be toggled by switching to the real user ID, then re-enabled +by reverting to the set-user-ID value. +Similarly, the effective group ID may be set to the value +of the real group ID or the saved set-group-ID. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The system calls will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +The user is not the super user and the ID +specified is not the real, effective ID, or saved ID. +.El +.Sh SEE ALSO +.Xr getgid 2 , +.Xr getuid 2 , +.Xr issetugid 2 , +.Xr setregid 2 , +.Xr setreuid 2 +.Sh STANDARDS +The +.Fn setuid +and +.Fn setgid +system calls are compliant with the +.St -p1003.1-90 +specification with +.Li _POSIX_SAVED_IDS +.\" Uncomment next line for !_POSIX_SAVED_IDS +not +defined with the permitted extensions from Appendix B.4.2.2. +The +.Fn seteuid +and +.Fn setegid +system calls are extensions based on the +.Tn POSIX +concept of +.Li _POSIX_SAVED_IDS , +and have been proposed for a future revision of the standard. +.Sh HISTORY +The +.Fn setuid +function appeared in +.At v1 . +The +.Fn setgid +function appeared in +.At v4 . +.Sh SECURITY CONSIDERATIONS +Read and write permissions to files are determined upon a call to +.Xr open 2 . +Once a file descriptor is open, dropping privilege does not affect +the process's read/write permissions, even if the user ID specified +has no read or write permissions to the file. +These files normally remain open in any new process executed, +resulting in a user being able to read or modify +potentially sensitive data. +.Pp +To prevent these files from remaining open after an +.Xr exec 3 +call, be sure to set the close-on-exec flag: +.Bd -literal +void +pseudocode(void) +{ + int fd; + /* ... */ + + fd = open("/path/to/sensitive/data", O_RDWR | O_CLOEXEC); + if (fd == -1) + err(1, "open"); + + /* ... */ + execve(path, argv, environ); +} +.Ed diff --git a/lib/libsys/shm_open.2 b/lib/libsys/shm_open.2 new file mode 100644 index 000000000000..8bea939690ba --- /dev/null +++ b/lib/libsys/shm_open.2 @@ -0,0 +1,622 @@ +.\" +.\" Copyright 2000 Massachusetts Institute of Technology +.\" +.\" Permission to use, copy, modify, and distribute this software and +.\" its documentation for any purpose and without fee is hereby +.\" granted, provided that both the above copyright notice and this +.\" permission notice appear in all copies, that both the above +.\" copyright notice and this permission notice appear in all +.\" supporting documentation, and that the name of M.I.T. not be used +.\" in advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. M.I.T. makes +.\" no representations about the suitability of this software for any +.\" purpose. It is provided "as is" without express or implied +.\" warranty. +.\" +.\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS +.\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE, +.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT +.\" SHALL M.I.T. 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. +.\" +.Dd January 30, 2023 +.Dt SHM_OPEN 2 +.Os +.Sh NAME +.Nm memfd_create , shm_create_largepage , shm_open , shm_rename, shm_unlink +.Nd "shared memory object operations" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/mman.h +.In fcntl.h +.Ft int +.Fn memfd_create "const char *name" "unsigned int flags" +.Ft int +.Fo shm_create_largepage +.Fa "const char *path" +.Fa "int flags" +.Fa "int psind" +.Fa "int alloc_policy" +.Fa "mode_t mode" +.Fc +.Ft int +.Fn shm_open "const char *path" "int flags" "mode_t mode" +.Ft int +.Fn shm_rename "const char *path_from" "const char *path_to" "int flags" +.Ft int +.Fn shm_unlink "const char *path" +.Sh DESCRIPTION +The +.Fn shm_open +function opens (or optionally creates) a +POSIX +shared memory object named +.Fa path . +The +.Fa flags +argument contains a subset of the flags used by +.Xr open 2 . +An access mode of either +.Dv O_RDONLY +or +.Dv O_RDWR +must be included in +.Fa flags . +The optional flags +.Dv O_CREAT , +.Dv O_EXCL , +and +.Dv O_TRUNC +may also be specified. +.Pp +If +.Dv O_CREAT +is specified, +then a new shared memory object named +.Fa path +will be created if it does not exist. +In this case, +the shared memory object is created with mode +.Fa mode +subject to the process' umask value. +If both the +.Dv O_CREAT +and +.Dv O_EXCL +flags are specified and a shared memory object named +.Fa path +already exists, +then +.Fn shm_open +will fail with +.Er EEXIST . +.Pp +Newly created objects start off with a size of zero. +If an existing shared memory object is opened with +.Dv O_RDWR +and the +.Dv O_TRUNC +flag is specified, +then the shared memory object will be truncated to a size of zero. +The size of the object can be adjusted via +.Xr ftruncate 2 +and queried via +.Xr fstat 2 . +.Pp +The new descriptor is set to close during +.Xr execve 2 +system calls; +see +.Xr close 2 +and +.Xr fcntl 2 . +.Pp +The constant +.Dv SHM_ANON +may be used for the +.Fa path +argument to +.Fn shm_open . +In this case, an anonymous, unnamed shared memory object is created. +Since the object has no name, +it cannot be removed via a subsequent call to +.Fn shm_unlink , +or moved with a call to +.Fn shm_rename . +Instead, +the shared memory object will be garbage collected when the last reference to +the shared memory object is removed. +The shared memory object may be shared with other processes by sharing the +file descriptor via +.Xr fork 2 +or +.Xr sendmsg 2 . +Attempting to open an anonymous shared memory object with +.Dv O_RDONLY +will fail with +.Er EINVAL . +All other flags are ignored. +.Pp +The +.Fn shm_create_largepage +function behaves similarly to +.Fn shm_open , +except that the +.Dv O_CREAT +flag is implicitly specified, and the returned +.Dq largepage +object is always backed by aligned, physically contiguous chunks of memory. +This ensures that the object can be mapped using so-called +.Dq superpages , +which can improve application performance in some workloads by reducing the +number of translation lookaside buffer (TLB) entries required to access a +mapping of the object, +and by reducing the number of page faults performed when accessing a mapping. +This happens automatically for all largepage objects. +.Pp +An existing largepage object can be opened using the +.Fn shm_open +function. +Largepage shared memory objects behave slightly differently from non-largepage +objects: +.Bl -bullet -offset indent +.It +Memory for a largepage object is allocated when the object is +extended using the +.Xr ftruncate 2 +system call, whereas memory for regular shared memory objects is allocated +lazily and may be paged out to a swap device when not in use. +.It +The size of a mapping of a largepage object must be a multiple of the +underlying large page size. +Most attributes of such a mapping can only be modified at the granularity +of the large page size. +For example, when using +.Xr munmap 2 +to unmap a portion of a largepage object mapping, or when using +.Xr mprotect 2 +to adjust protections of a mapping of a largepage object, the starting address +must be large page size-aligned, and the length of the operation must be a +multiple of the large page size. +If not, the corresponding system call will fail and set +.Va errno +to +.Er EINVAL . +.El +.Pp +The +.Fa psind +argument to +.Fn shm_create_largepage +specifies the size of large pages used to back the object. +This argument is an index into the page sizes array returned by +.Xr getpagesizes 3 . +In particular, all large pages backing a largepage object must be of the +same size. +For example, on a system with large page sizes of 2MB and 1GB, a 2GB largepage +object will consist of either 1024 2MB pages, or 2 1GB pages, depending on +the value specified for the +.Fa psind +argument. +The +.Fa alloc_policy +parameter specifies what happens when an attempt to use +.Xr ftruncate 2 +to allocate memory for the object fails. +The following values are accepted: +.Bl -tag -offset indent -width SHM_ +.It Dv SHM_LARGEPAGE_ALLOC_DEFAULT +If the (non-blocking) memory allocation fails because there is insufficient free +contiguous memory, the kernel will attempt to defragment physical memory and +try another allocation. +The subsequent allocation may or may not succeed. +If this subsequent allocation also fails, +.Xr ftruncate 2 +will fail and set +.Va errno +to +.Er ENOMEM . +.It Dv SHM_LARGEPAGE_ALLOC_NOWAIT +If the memory allocation fails, +.Xr ftruncate 2 +will fail and set +.Va errno +to +.Er ENOMEM . +.It Dv SHM_LARGEPAGE_ALLOC_HARD +The kernel will attempt defragmentation until the allocation succeeds, +or an unblocked signal is delivered to the thread. +However, it is possible for physical memory to be fragmented such that the +allocation will never succeed. +.El +.Pp +The +.Dv FIOSSHMLPGCNF +and +.Dv FIOGSHMLPGCNF +.Xr ioctl 2 +commands can be used with a largepage shared memory object to get and set +largepage object parameters. +Both commands operate on the following structure: +.Bd -literal +struct shm_largepage_conf { + int psind; + int alloc_policy; +}; + +.Ed +The +.Dv FIOGSHMLPGCNF +command populates this structure with the current values of these parameters, +while the +.Dv FIOSSHMLPGCNF +command modifies the largepage object. +Currently only the +.Va alloc_policy +parameter may be modified. +Internally, +.Fn shm_create_largepage +works by creating a regular shared memory object using +.Fn shm_open , +and then converting it into a largepage object using the +.Dv FIOSSHMLPGCNF +ioctl command. +.Pp +The +.Fn shm_rename +system call atomically removes a shared memory object named +.Fa path_from +and relinks it at +.Fa path_to . +If another object is already linked at +.Fa path_to , +that object will be unlinked, unless one of the following flags are provided: +.Bl -tag -offset indent -width Er +.It Er SHM_RENAME_EXCHANGE +Atomically exchange the shms at +.Fa path_from +and +.Fa path_to . +.It Er SHM_RENAME_NOREPLACE +Return an error if an shm exists at +.Fa path_to , +rather than unlinking it. +.El +.Pp +The +.Fn shm_unlink +system call removes a shared memory object named +.Fa path . +.Pp +The +.Fn memfd_create +function creates an anonymous shared memory object, identical to that created +by +.Fn shm_open +when +.Dv SHM_ANON +is specified. +Newly created objects start off with a size of zero. +The size of the new object must be adjusted via +.Xr ftruncate 2 . +.Pp +The +.Fa name +argument must not be +.Dv NULL , +but it may be an empty string. +The length of the +.Fa name +argument may not exceed +.Dv NAME_MAX +minus six characters for the prefix +.Dq memfd: , +which will be prepended. +The +.Fa name +argument is intended solely for debugging purposes and will never be used by the +kernel to identify a memfd. +Names are therefore not required to be unique. +.Pp +The following +.Fa flags +may be specified to +.Fn memfd_create : +.Bl -tag -width MFD_ALLOW_SEALING +.It Dv MFD_CLOEXEC +Set +.Dv FD_CLOEXEC +on the resulting file descriptor. +.It Dv MFD_ALLOW_SEALING +Allow adding seals to the resulting file descriptor using the +.Dv F_ADD_SEALS +.Xr fcntl 2 +command. +.It Dv MFD_HUGETLB +This flag is currently unsupported. +.El +.Sh RETURN VALUES +If successful, +.Fn memfd_create +and +.Fn shm_open +both return a non-negative integer, +and +.Fn shm_rename +and +.Fn shm_unlink +return zero. +All functions return -1 on failure, and set +.Va errno +to indicate the error. +.Sh COMPATIBILITY +The +.Fn shm_create_largepage +and +.Fn shm_rename +functions are +.Fx +extensions, as is support for the +.Dv SHM_ANON +value in +.Fn shm_open . +.Pp +The +.Fa path , +.Fa path_from , +and +.Fa path_to +arguments do not necessarily represent a pathname (although they do in +most other implementations). +Two processes opening the same +.Fa path +are guaranteed to access the same shared memory object if and only if +.Fa path +begins with a slash +.Pq Ql \&/ +character. +.Pp +Only the +.Dv O_RDONLY , +.Dv O_RDWR , +.Dv O_CREAT , +.Dv O_EXCL , +and +.Dv O_TRUNC +flags may be used in portable programs. +.Pp +POSIX +specifications state that the result of using +.Xr open 2 , +.Xr read 2 , +or +.Xr write 2 +on a shared memory object, or on the descriptor returned by +.Fn shm_open , +is undefined. +However, the +.Fx +kernel implementation explicitly includes support for +.Xr read 2 +and +.Xr write 2 . +.Pp +.Fx +also supports zero-copy transmission of data from shared memory +objects with +.Xr sendfile 2 . +.Pp +Neither shared memory objects nor their contents persist across reboots. +.Pp +Writes do not extend shared memory objects, so +.Xr ftruncate 2 +must be called before any data can be written. +See +.Sx EXAMPLES . +.Sh EXAMPLES +This example fails without the call to +.Xr ftruncate 2 : +.Bd -literal -compact + + uint8_t buffer[getpagesize()]; + ssize_t len; + int fd; + + fd = shm_open(SHM_ANON, O_RDWR | O_CREAT, 0600); + if (fd < 0) + err(EX_OSERR, "%s: shm_open", __func__); + if (ftruncate(fd, getpagesize()) < 0) + err(EX_IOERR, "%s: ftruncate", __func__); + len = pwrite(fd, buffer, getpagesize(), 0); + if (len < 0) + err(EX_IOERR, "%s: pwrite", __func__); + if (len != getpagesize()) + errx(EX_IOERR, "%s: pwrite length mismatch", __func__); +.Ed +.Sh ERRORS +.Fn memfd_create +fails with these error codes for these conditions: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa name +argument was NULL. +.It Bq Er EINVAL +The +.Fa name +argument was too long. +.Pp +An invalid or unsupported flag was included in +.Fa flags . +.It Bq Er EMFILE +The process has already reached its limit for open file descriptors. +.It Bq Er ENFILE +The system file table is full. +.It Bq Er ENOSYS +In +.Fa memfd_create , +.Dv MFD_HUGETLB +was specified in +.Fa flags , +and this system does not support forced hugetlb mappings. +.El +.Pp +.Fn shm_open +fails with these error codes for these conditions: +.Bl -tag -width Er +.It Bq Er EINVAL +A flag other than +.Dv O_RDONLY , +.Dv O_RDWR , +.Dv O_CREAT , +.Dv O_EXCL , +or +.Dv O_TRUNC +was included in +.Fa flags . +.It Bq Er EMFILE +The process has already reached its limit for open file descriptors. +.It Bq Er ENFILE +The system file table is full. +.It Bq Er EINVAL +.Dv O_RDONLY +was specified while creating an anonymous shared memory object via +.Dv SHM_ANON . +.It Bq Er EFAULT +The +.Fa path +argument points outside the process' allocated address space. +.It Bq Er ENAMETOOLONG +The entire pathname exceeds 1023 characters. +.It Bq Er EINVAL +The +.Fa path +does not begin with a slash +.Pq Ql \&/ +character. +.It Bq Er ENOENT +.Dv O_CREAT +is not specified and the named shared memory object does not exist. +.It Bq Er EEXIST +.Dv O_CREAT +and +.Dv O_EXCL +are specified and the named shared memory object does exist. +.It Bq Er EACCES +The required permissions (for reading or reading and writing) are denied. +.It Bq Er ECAPMODE +The process is running in capability mode (see +.Xr capsicum 4 ) +and attempted to create a named shared memory object. +.El +.Pp +.Fn shm_create_largepage +can fail for the reasons listed above. +It also fails with these error codes for the following conditions: +.Bl -tag -width Er +.It Bq Er ENOTTY +The kernel does not support large pages on the current platform. +.El +.Pp +The following errors are defined for +.Fn shm_rename : +.Bl -tag -width Er +.It Bq Er EFAULT +The +.Fa path_from +or +.Fa path_to +argument points outside the process' allocated address space. +.It Bq Er ENAMETOOLONG +The entire pathname exceeds 1023 characters. +.It Bq Er ENOENT +The shared memory object at +.Fa path_from +does not exist. +.It Bq Er EACCES +The required permissions are denied. +.It Bq Er EEXIST +An shm exists at +.Fa path_to , +and the +.Dv SHM_RENAME_NOREPLACE +flag was provided. +.El +.Pp +.Fn shm_unlink +fails with these error codes for these conditions: +.Bl -tag -width Er +.It Bq Er EFAULT +The +.Fa path +argument points outside the process' allocated address space. +.It Bq Er ENAMETOOLONG +The entire pathname exceeds 1023 characters. +.It Bq Er ENOENT +The named shared memory object does not exist. +.It Bq Er EACCES +The required permissions are denied. +.Fn shm_unlink +requires write permission to the shared memory object. +.El +.Sh SEE ALSO +.Xr posixshmcontrol 1 , +.Xr close 2 , +.Xr fstat 2 , +.Xr ftruncate 2 , +.Xr ioctl 2 , +.Xr mmap 2 , +.Xr munmap 2 , +.Xr sendfile 2 +.Sh STANDARDS +The +.Fn memfd_create +function is expected to be compatible with the Linux system call of the same +name. +.Pp +The +.Fn shm_open +and +.Fn shm_unlink +functions are believed to conform to +.St -p1003.1b-93 . +.Sh HISTORY +The +.Fn memfd_create +function appeared in +.Fx 13.0 . +.Pp +The +.Fn shm_open +and +.Fn shm_unlink +functions first appeared in +.Fx 4.3 . +The functions were reimplemented as system calls using shared memory objects +directly rather than files in +.Fx 8.0 . +.Pp +.Fn shm_rename +first appeared in +.Fx 13.0 +as a +.Fx +extension. +.Sh AUTHORS +.An Garrett A. Wollman Aq Mt wollman@FreeBSD.org +(C library support and this manual page) +.Pp +.An Matthew Dillon Aq Mt dillon@FreeBSD.org +.Pq Dv MAP_NOSYNC +.Pp +.An Matthew Bryan Aq Mt matthew.bryan@isilon.com +.Pq Dv shm_rename implementation diff --git a/lib/libsys/shmat.2 b/lib/libsys/shmat.2 new file mode 100644 index 000000000000..16d4b930995d --- /dev/null +++ b/lib/libsys/shmat.2 @@ -0,0 +1,154 @@ +.\" +.\" Copyright (c) 1995 David Hovemeyer <daveho@infocom.com> +.\" +.\" All rights reserved. +.\" +.\" 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 DEVELOPERS ``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 DEVELOPERS 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. +.\" +.Dd January 14, 2019 +.Dt SHMAT 2 +.Os +.Sh NAME +.Nm shmat , +.Nm shmdt +.Nd attach or detach shared memory +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/ipc.h +.In sys/shm.h +.Ft void * +.Fn shmat "int shmid" "const void *addr" "int flag" +.Ft int +.Fn shmdt "const void *addr" +.Sh DESCRIPTION +The +.Fn shmat +system call +attaches the shared memory segment identified by +.Fa shmid +to the calling process's address space. +The address where the segment +is attached is determined as follows: +.\" +.\" These are cribbed almost exactly from Stevens, _Advanced Programming in +.\" the UNIX Environment_. +.\" +.Bl -bullet +.It +If +.Fa addr +is 0, the segment is attached at an address selected by the +kernel. +.It +If +.Fa addr +is nonzero and +.Va SHM_RND +is not specified in +.Fa flag , +the segment is attached the specified address. +.It +If +.Fa addr +is specified and +.Va SHM_RND +is specified, +.Fa addr +is rounded down to the nearest multiple of SHMLBA. +.El +.Pp +If the +.Va SHM_REMAP +flag is specified and the passed +.Fa addr +is not +.Dv NULL , +any existing mappings in the virtual addresses range are +cleared before the segment is attached. +If the flag is not specified, +.Fa addr +is not +.Dv NULL , +and the virtual address range contains +some pre-existing mappings, the +.Fn shmat +call fails. +.Pp +The +.Fn shmdt +system call +detaches the shared memory segment at the address specified by +.Fa addr +from the calling process's address space. +.Sh RETURN VALUES +Upon success, +.Fn shmat +returns the address where the segment is attached; otherwise, -1 +is returned and +.Va errno +is set to indicate the error. +.Pp +.Rv -std shmdt +.Sh ERRORS +The +.Fn shmat +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +No shared memory segment was found corresponding to +.Fa shmid . +.It Bq Er EINVAL +The +.Fa addr +argument +was not an acceptable address. +.It Bq Er ENOMEM +The specified +.Fa addr +cannot be used for mapping, for instance due to the amount of available +space being smaller than the segment size, +or because pre-existing mappings are in the range and no +.Va SHM_REMAP +flag was provided. +.It Bq Er EMFILE +Failed to attach the shared memory segment because the per-process +.Va kern.ipc.shmseg +.Xr sysctl 3 +limit was reached. +.El +.Pp +The +.Fn shmdt +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa addr +argument +does not point to a shared memory segment. +.El +.Sh "SEE ALSO" +.Xr shmctl 2 , +.Xr shmget 2 diff --git a/lib/libsys/shmctl.2 b/lib/libsys/shmctl.2 new file mode 100644 index 000000000000..6c2259981310 --- /dev/null +++ b/lib/libsys/shmctl.2 @@ -0,0 +1,139 @@ +.\" +.\" Copyright (c) 1995 David Hovemeyer <daveho@infocom.com> +.\" +.\" All rights reserved. +.\" +.\" 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 DEVELOPERS ``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 DEVELOPERS 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. +.\" +.Dd October 10, 2015 +.Dt SHMCTL 2 +.Os +.Sh NAME +.Nm shmctl +.Nd shared memory control +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/ipc.h +.In sys/shm.h +.Ft int +.Fn shmctl "int shmid" "int cmd" "struct shmid_ds *buf" +.Sh DESCRIPTION +Performs the action specified by +.Fa cmd +on the shared memory segment identified by +.Fa shmid : +.Bl -tag -width SHM_UNLOCKX +.It Dv IPC_STAT +Fetch the segment's +.Fa "struct shmid_ds" , +storing it in the memory pointed to by +.Fa buf . +.\" +.\" XXX need to make sure that this is correct for FreeBSD +.\" +.It Dv IPC_SET +Changes the +.Fa shm_perm.uid , +.Fa shm_perm.gid , +and +.Fa shm_perm.mode +members of the segment's +.Fa "struct shmid_ds" +to match those of the struct pointed to by +.Fa buf . +The calling process's effective uid must +match either +.Fa shm_perm.uid +or +.Fa shm_perm.cuid , +or it must have superuser privileges. +.It Dv IPC_RMID +Removes the segment from the system. +The removal will not take +effect until all processes having attached the segment have exited. +For the operation +to succeed, the calling process's effective uid must match +.Fa shm_perm.uid +or +.Fa shm_perm.cuid , +or the process must have superuser privileges. +If the +.Va kern.ipc.shm_allow_removed +.Xr sysctl 3 +variable is set to 0, once the IPC_RMID operation has taken place, +no further processes will be allowed to attach the segment. +.\" .It Dv SHM_LOCK +.\" Locks the segment in memory. The calling process must have +.\" superuser privileges. Not implemented in FreeBSD. +.\" .It Dv SHM_UNLOCK +.\" Unlocks the segment from memory. The calling process must +.\" have superuser privileges. Not implemented in FreeBSD. +.El +.Pp +The +.Vt shmid_ds +structure is defined as follows: +.\" +.\" I fiddled with the spaces a bit to make it fit well when viewed +.\" with nroff, but otherwise it is straight from sys/shm.h +.\" +.Bd -literal +struct shmid_ds { + struct ipc_perm shm_perm; /* operation permission structure */ + size_t shm_segsz; /* size of segment in bytes */ + pid_t shm_lpid; /* process ID of last shared memory op */ + pid_t shm_cpid; /* process ID of creator */ + int shm_nattch; /* number of current attaches */ + time_t shm_atime; /* time of last shmat() */ + time_t shm_dtime; /* time of last shmdt() */ + time_t shm_ctime; /* time of last change by shmctl() */ +}; +.Ed +.Sh RETURN VALUES +.Rv -std shmctl +.Sh ERRORS +The +.Fn shmctl +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid operation, or +no shared memory segment was found corresponding to +.Fa shmid . +.\" +.\" XXX I think the following is right: ipcperm() only returns EPERM +.\" when an attempt is made to modify (IPC_M) by a non-creator +.\" non-owner +.It Bq Er EPERM +The calling process's effective uid does not match the uid of +the shared memory segment's owner or creator. +.It Bq Er EACCES +Permission denied due to mismatch between operation and mode of +shared memory segment. +.El +.Sh "SEE ALSO" +.Xr shmat 2 , +.Xr shmdt 2 , +.Xr shmget 2 , +.Xr ftok 3 diff --git a/lib/libsys/shmget.2 b/lib/libsys/shmget.2 new file mode 100644 index 000000000000..9bc742e016a8 --- /dev/null +++ b/lib/libsys/shmget.2 @@ -0,0 +1,140 @@ +.\" +.\" Copyright (c) 1995 David Hovemeyer <daveho@infocom.com> +.\" +.\" All rights reserved. +.\" +.\" 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 DEVELOPERS ``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 DEVELOPERS 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. +.\" +.Dd March 4, 2018 +.Dt SHMGET 2 +.Os +.Sh NAME +.Nm shmget +.Nd obtain a shared memory identifier +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/shm.h +.Ft int +.Fn shmget "key_t key" "size_t size" "int flag" +.Sh DESCRIPTION +Based on the values of +.Fa key +and +.Fa flag , +.Fn shmget +returns the identifier of a newly created or previously existing shared +memory segment. +.\" +.\" The following bit about keys and modes also applies to semaphores +.\" and message queues. +.\" +The key +is analogous to a filename: it provides a handle that names an +IPC object. +There are three ways to specify a key: +.Bl -bullet +.It +IPC_PRIVATE may be specified, in which case a new IPC object +will be created. +.It +An integer constant may be specified. +If no IPC object corresponding +to +.Fa key +is specified and the IPC_CREAT bit is set in +.Fa flag , +a new one will be created. +.It +The +.Xr ftok 3 +may be used to generate a key from a pathname. +.El +.Pp +The mode of a newly created IPC object is determined by +which are set by ORing these constants into the +.Fa flag +argument: +.Bl -tag -width 0000 +.It Dv 0400 +Read access for owner. +.It Dv 0200 +Write access for owner. +.It Dv 0040 +Read access for group. +.It Dv 0020 +Write access for group. +.It Dv 0004 +Read access for other. +.It Dv 0002 +Write access for other. +.El +.\" +.\" XXX - we should also mention how uid, euid, and gid affect ownership +.\" and use +.\" +.\" end section about keys and modes +.\" +.Pp +When creating a new shared memory segment, +.Fa size +indicates the desired size of the new segment in bytes. +The size +of the segment may be rounded up to a multiple convenient to the +kernel (i.e., the page size). +.Sh RETURN VALUES +Upon successful completion, +.Fn shmget +returns the positive integer identifier of a shared memory segment. +Otherwise, -1 is returned and +.Va errno +set to indicate the error. +.Sh ERRORS +The +.Fn shmget +system call +will fail if: +.Bl -tag -width Er +.\" +.\" XXX What about ipcperm failing? +.\" +.It Bq Er EINVAL +Size specified is greater than the size of the previously existing segment. +Size specified is less than the system imposed minimum, or greater than +the system imposed maximum. +.It Bq Er ENOENT +No shared memory segment was found matching +.Fa key , +and IPC_CREAT was not specified. +.It Bq Er ENOSPC +The kernel was unable to allocate enough memory to +satisfy the request. +.It Bq Er EEXIST +IPC_CREAT and IPC_EXCL were specified, and a shared memory segment +corresponding to +.Fa key +already exists. +.El +.Sh "SEE ALSO" +.Xr shmat 2 , +.Xr shmctl 2 , +.Xr shmdt 2 , +.Xr ftok 3 diff --git a/lib/libsys/shutdown.2 b/lib/libsys/shutdown.2 new file mode 100644 index 000000000000..b361527d925c --- /dev/null +++ b/lib/libsys/shutdown.2 @@ -0,0 +1,168 @@ +.\" Copyright (c) 2007 Bruce M. Simpson. +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd July 27, 2015 +.Dt SHUTDOWN 2 +.Os +.Sh NAME +.Nm shutdown +.Nd disable sends and/or receives on a socket +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.Ft int +.Fn shutdown "int s" "int how" +.Sh DESCRIPTION +The +.Fn shutdown +system call disables sends or receives on a socket. +The +.Fa how +argument specifies the type of shutdown. +Possible values are: +.Bl -tag -width ".Dv SHUT_RDWR" +.It Dv SHUT_RD +Further receives will be disallowed. +.It Dv SHUT_WR +Further sends will be disallowed. +This may cause actions specific to the protocol family of the socket +.Fa s +to happen; see +.Sx IMPLEMENTATION NOTES . +.It Dv SHUT_RDWR +Further sends and receives will be disallowed. +Implies +.Dv SHUT_WR . +.El +.Pp +If the file descriptor +.Fa s +is associated with a +.Dv SOCK_STREAM +socket, all or part of the full-duplex connection will be shut down. +.\" +.Sh IMPLEMENTATION NOTES +The following protocol specific actions apply to the use of +.Dv SHUT_WR +(and potentially also +.Dv SHUT_RDWR ) , +based on the properties of the socket associated with the file descriptor +.Fa s . +.Bl -column ".Dv PF_INET6" ".Dv SOCK_STREAM" ".Dv IPPROTO_SCTP" +.It Sy Domain Ta Sy Type Ta Sy Protocol Ta Sy Action +.It Dv PF_INET Ta Dv SOCK_DGRAM Ta Dv IPPROTO_SCTP Ta +Failure, +as socket is not connected. +.It Dv PF_INET Ta Dv SOCK_DGRAM Ta Dv IPPROTO_UDP Ta +Failure, +as socket is not connected. +.It Dv PF_INET Ta Dv SOCK_STREAM Ta Dv IPPROTO_SCTP Ta +Send queued data and tear down association. +.It Dv PF_INET Ta Dv SOCK_STREAM Ta Dv IPPROTO_TCP Ta +Send queued data, wait for ACK, then send FIN. +.It Dv PF_INET6 Ta Dv SOCK_DGRAM Ta Dv IPPROTO_SCTP Ta +Failure, +as socket is not connected. +.It Dv PF_INET6 Ta Dv SOCK_DGRAM Ta Dv IPPROTO_UDP Ta +Failure, +as socket is not connected. +.It Dv PF_INET6 Ta Dv SOCK_STREAM Ta Dv IPPROTO_SCTP Ta +Send queued data and tear down association. +.It Dv PF_INET6 Ta Dv SOCK_STREAM Ta Dv IPPROTO_TCP Ta +Send queued data, wait for ACK, then send FIN. +.El +.\" +.Sh RETURN VALUES +.Rv -std shutdown +.Sh ERRORS +The +.Fn shutdown +system call fails if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa s +argument is not a valid file descriptor. +.It Bq Er EINVAL +The +.Fa how +argument is invalid. +.It Bq Er ENOTCONN +The +.Fa s +argument specifies a socket which is not connected. +.It Bq Er ENOTSOCK +The +.Fa s +argument does not refer to a socket. +.El +.Sh SEE ALSO +.Xr connect 2 , +.Xr socket 2 , +.Xr inet 4 , +.Xr inet6 4 +.Sh STANDARDS +The +.Fn shutdown +system call is expected to comply with +.St -p1003.1g-2000 , +when finalized. +.Sh HISTORY +The +.Fn shutdown +system call appeared in +.Bx 4.2 . +The +.Dv SHUT_RD , SHUT_WR , +and +.Dv SHUT_RDWR +constants appeared in +.St -p1003.1g-2000 . +.Sh AUTHORS +.An -nosplit +This manual page was updated by +.An Bruce M. Simpson Aq Mt bms@FreeBSD.org +to reflect how +.Fn shutdown +behaves with +.Dv PF_INET +and +.Dv PF_INET6 +sockets. +.Sh BUGS +The ICMP +.Dq Li "port unreachable" +message should be generated in response to +datagrams received on a local port to which +.Fa s +is bound +after +.Fn shutdown +is called. diff --git a/lib/libsys/sigaction.2 b/lib/libsys/sigaction.2 new file mode 100644 index 000000000000..9f49fb38245a --- /dev/null +++ b/lib/libsys/sigaction.2 @@ -0,0 +1,792 @@ +.\" Copyright (c) 1980, 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd December 1, 2023 +.Dt SIGACTION 2 +.Os +.Sh NAME +.Nm sigaction +.Nd software signal facilities +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Bd -literal +struct sigaction { + void (*sa_handler)(int); + void (*sa_sigaction)(int, siginfo_t *, void *); + int sa_flags; /* see signal options below */ + sigset_t sa_mask; /* signal mask to apply */ +}; +.Ed +.Pp +.Ft int +.Fo sigaction +.Fa "int sig" +.Fa "const struct sigaction * restrict act" +.Fa "struct sigaction * restrict oact" +.Fc +.Sh DESCRIPTION +The system defines a set of signals that may be delivered to a process. +Signal delivery resembles the occurrence of a hardware interrupt: +the signal is normally blocked from further occurrence, the current thread +context is saved, and a new one is built. +A process may specify a +.Em handler +to which a signal is delivered, or specify that a signal is to be +.Em ignored . +A process may also specify that a default action is to be taken +by the system when a signal occurs. +A signal may also be +.Em blocked +for a thread, +in which case it will not be delivered to that thread until it is +.Em unblocked . +The action to be taken on delivery is determined at the time +of delivery. +Normally, signal handlers execute on the current stack +of the thread. +This may be changed, on a per-handler basis, +so that signals are taken on a special +.Em "signal stack" . +.Pp +Signal routines normally execute with the signal that caused their +invocation +.Em blocked , +but other signals may yet occur. +A global +.Em "signal mask" +defines the set of signals currently blocked from delivery +to a thread. +The signal mask for a thread is initialized +from that of its parent (normally empty). +It may be changed with a +.Xr sigprocmask 2 +or +.Xr pthread_sigmask 3 +call, or when a signal is delivered to the thread. +.Pp +When a signal +condition arises for a process or thread, the signal is added to a set of +signals pending for the process or thread. +Whether the signal is directed at the process in general or at a specific +thread depends on how it is generated. +For signals directed at a specific thread, +if the signal is not currently +.Em blocked +by the thread then it is delivered to the thread. +For signals directed at the process, +if the signal is not currently +.Em blocked +by all threads then it is delivered to one thread that does not have it blocked +(the selection of which is unspecified). +Signals may be delivered any time a thread enters the operating system +(e.g., during a system call, page fault or trap, or clock interrupt). +If multiple signals are ready to be delivered at the same time, +any signals that could be caused by traps are delivered first. +Additional signals may be processed at the same time, with each +appearing to interrupt the handlers for the previous signals +before their first instructions. +The set of pending signals is returned by the +.Xr sigpending 2 +system call. +When a caught signal +is delivered, the current state of the thread is saved, +a new signal mask is calculated (as described below), +and the signal handler is invoked. +The call to the handler +is arranged so that if the signal handling routine returns +normally the thread will resume execution in the context +from before the signal's delivery. +If the thread wishes to resume in a different context, then it +must arrange to restore the previous context itself. +.Pp +When a signal is delivered to a thread a new signal mask is +installed for the duration of the process' signal handler +(or until a +.Xr sigprocmask 2 +system call is made). +This mask is formed by taking the union of the current signal mask set, +the signal to be delivered, and +the signal mask associated with the handler to be invoked. +.Pp +The +.Fn sigaction +system call +assigns an action for a signal specified by +.Fa sig . +If +.Fa act +is non-NULL, it specifies an action +.Dv ( SIG_DFL , +.Dv SIG_IGN , +or a handler routine) and mask to be used when delivering the specified signal. +If +.Fa oact +is non-NULL, the previous handling information for the signal +is returned to the user. +.Pp +The above declaration of +.Vt "struct sigaction" +is not literal. +It is provided only to list the accessible members. +See +.In sys/signal.h +for the actual definition. +In particular, the storage occupied by +.Va sa_handler +and +.Va sa_sigaction +overlaps, and it is nonsensical for an application to attempt to use both +simultaneously. +.Pp +Once a signal handler is installed, it normally remains installed +until another +.Fn sigaction +system call is made, or an +.Xr execve 2 +is performed. +A signal-specific default action may be reset by +setting +.Va sa_handler +to +.Dv SIG_DFL . +The defaults are process termination, possibly with core dump; +no action; stopping the process; or continuing the process. +See the signal list below for each signal's default action. +If +.Va sa_handler +is +.Dv SIG_DFL , +the default action for the signal is to discard the signal, +and if a signal is pending, +the pending signal is discarded even if the signal is masked. +If +.Va sa_handler +is set to +.Dv SIG_IGN +current and pending instances +of the signal are ignored and discarded. +.Pp +Options may be specified by setting +.Va sa_flags . +The meaning of the various bits is as follows: +.Bl -tag -offset indent -width SA_RESETHANDXX +.It Dv SA_NOCLDSTOP +If this bit is set when installing a catching function +for the +.Dv SIGCHLD +signal, +the +.Dv SIGCHLD +signal will be generated only when a child process exits, +not when a child process stops. +.It Dv SA_NOCLDWAIT +If this bit is set when calling +.Fn sigaction +for the +.Dv SIGCHLD +signal, the system will not create zombie processes when children of +the calling process exit. +If the calling process subsequently issues a +.Xr wait 2 +(or equivalent), it blocks until all of the calling process's child +processes terminate, and then returns a value of \-1 with +.Va errno +set to +.Er ECHILD . +The same effect of avoiding zombie creation can also be achieved by setting +.Va sa_handler +for +.Dv SIGCHLD +to +.Dv SIG_IGN . +.It Dv SA_ONSTACK +If this bit is set, the system will deliver the signal to the process +on a +.Em "signal stack" , +specified by each thread with +.Xr sigaltstack 2 . +.It Dv SA_NODEFER +If this bit is set, further occurrences of the delivered signal are +not masked during the execution of the handler. +.It Dv SA_RESETHAND +If this bit is set, the handler is reset back to +.Dv SIG_DFL +at the moment the signal is delivered. +.It Dv SA_RESTART +See paragraph below. +.It Dv SA_SIGINFO +If this bit is set, the handler function is assumed to be pointed to by the +.Va sa_sigaction +member of +.Vt "struct sigaction" +and should match the prototype shown above or as below in +.Sx EXAMPLES . +This bit should not be set when assigning +.Dv SIG_DFL +or +.Dv SIG_IGN . +.El +.Pp +If a signal is caught during the system calls listed below, +the call may be forced to terminate +with the error +.Er EINTR , +the call may return with a data transfer shorter than requested, +or the call may be restarted. +Restart of pending calls is requested +by setting the +.Dv SA_RESTART +bit in +.Va sa_flags . +The affected system calls include +.Xr open 2 , +.Xr read 2 , +.Xr write 2 , +.Xr sendto 2 , +.Xr recvfrom 2 , +.Xr sendmsg 2 +and +.Xr recvmsg 2 +on a communications channel or a slow device (such as a terminal, +but not a regular file) +and during a +.Xr wait 2 +or +.Xr ioctl 2 . +However, calls that have already committed are not restarted, +but instead return a partial success (for example, a short read count). +.Pp +After a +.Xr pthread_create 3 +the signal mask is inherited by the new thread and +the set of pending signals and the signal stack for the new thread are empty. +.Pp +After a +.Xr fork 2 +or +.Xr vfork 2 +all signals, the signal mask, the signal stack, +and the restart/interrupt flags are inherited by the child. +.Pp +The +.Xr execve 2 +system call reinstates the default +action for all signals which were caught and +resets all signals to be caught on the user stack. +Ignored signals remain ignored; +the signal mask remains the same; +signals that restart pending system calls continue to do so. +.Pp +The following is a list of all signals +with names as in the include file +.In signal.h : +.Bl -column SIGVTALARMXX "create core imagexxx" +.It Sy NAME Ta Sy Default Action Ta Sy Description +.It Dv SIGHUP Ta terminate process Ta terminal line hangup +.It Dv SIGINT Ta terminate process Ta interrupt program +.It Dv SIGQUIT Ta create core image Ta quit program +.It Dv SIGILL Ta create core image Ta illegal instruction +.It Dv SIGTRAP Ta create core image Ta trace trap +.It Dv SIGABRT Ta create core image Ta Xr abort 3 call (formerly Dv SIGIOT ) +.It Dv SIGEMT Ta create core image Ta emulate instruction executed +.It Dv SIGFPE Ta create core image Ta floating-point exception +.It Dv SIGKILL Ta terminate process Ta kill program +.It Dv SIGBUS Ta create core image Ta bus error +.It Dv SIGSEGV Ta create core image Ta segmentation violation +.It Dv SIGSYS Ta create core image Ta non-existent system call invoked +.It Dv SIGPIPE Ta terminate process Ta write on a pipe with no reader +.It Dv SIGALRM Ta terminate process Ta real-time timer expired +.It Dv SIGTERM Ta terminate process Ta software termination signal +.It Dv SIGURG Ta discard signal Ta urgent condition present on socket +.It Dv SIGSTOP Ta stop process Ta stop (cannot be caught or ignored) +.It Dv SIGTSTP Ta stop process Ta stop signal generated from keyboard +.It Dv SIGCONT Ta discard signal Ta continue after stop +.It Dv SIGCHLD Ta discard signal Ta child status has changed +.It Dv SIGTTIN Ta stop process Ta background read attempted from control terminal +.It Dv SIGTTOU Ta stop process Ta background write attempted to control terminal +.It Dv SIGIO Ta discard signal Ta I/O is possible on a descriptor (see Xr fcntl 2 ) +.It Dv SIGXCPU Ta terminate process Ta cpu time limit exceeded (see Xr setrlimit 2 ) +.It Dv SIGXFSZ Ta terminate process Ta file size limit exceeded (see Xr setrlimit 2 ) +.It Dv SIGVTALRM Ta terminate process Ta virtual time alarm (see Xr setitimer 2 ) +.It Dv SIGPROF Ta terminate process Ta profiling timer alarm (see Xr setitimer 2 ) +.It Dv SIGWINCH Ta discard signal Ta window size change +.It Dv SIGINFO Ta discard signal Ta status request from keyboard +.It Dv SIGUSR1 Ta terminate process Ta user defined signal 1 +.It Dv SIGUSR2 Ta terminate process Ta user defined signal 2 +.El +.Sh NOTE +The +.Va sa_mask +field specified in +.Fa act +is not allowed to block +.Dv SIGKILL +or +.Dv SIGSTOP . +Any attempt to do so will be silently ignored. +.Pp +The following functions are either reentrant or not interruptible +by signals and are async-signal safe. +Therefore applications may +invoke them, without restriction, from signal-catching functions +or from a child process after calling +.Xr fork 2 +in a multi-threaded process: +.Pp +Base Interfaces: +.Pp +.Fn _Exit , +.Fn _exit , +.Fn accept , +.Fn access , +.Fn alarm , +.Fn bind , +.Fn cfgetispeed , +.Fn cfgetospeed , +.Fn cfsetispeed , +.Fn cfsetospeed , +.Fn chdir , +.Fn chmod , +.Fn chown , +.Fn close , +.Fn connect , +.Fn creat , +.Fn dup , +.Fn dup2 , +.Fn execl , +.Fn execle , +.Fn execv , +.Fn execve , +.Fn faccessat , +.Fn fchdir , +.Fn fchmod , +.Fn fchmodat , +.Fn fchown , +.Fn fchownat , +.Fn fcntl , +.Fn _Fork , +.Fn fstat , +.Fn fstatat , +.Fn fsync , +.Fn ftruncate , +.Fn getegid , +.Fn geteuid , +.Fn getgid , +.Fn getgroups , +.Fn getpeername , +.Fn getpgrp , +.Fn getpid , +.Fn getppid , +.Fn getsockname , +.Fn getsockopt , +.Fn getuid , +.Fn kill , +.Fn link , +.Fn linkat , +.Fn listen , +.Fn lseek , +.Fn lstat , +.Fn mkdir , +.Fn mkdirat , +.Fn mkfifo , +.Fn mkfifoat , +.Fn mknod , +.Fn mknodat , +.Fn open , +.Fn openat , +.Fn pause , +.Fn pipe , +.Fn poll , +.Fn pselect , +.Fn pthread_sigmask , +.Fn raise , +.Fn read , +.Fn readlink , +.Fn readlinkat , +.Fn recv , +.Fn recvfrom , +.Fn recvmsg , +.Fn rename , +.Fn renameat , +.Fn rmdir , +.Fn select , +.Fn send , +.Fn sendmsg , +.Fn sendto , +.Fn setgid , +.Fn setpgid , +.Fn setsid , +.Fn setsockopt , +.Fn setuid , +.Fn shutdown , +.Fn sigaction , +.Fn sigaddset , +.Fn sigdelset , +.Fn sigemptyset , +.Fn sigfillset , +.Fn sigismember , +.Fn signal , +.Fn sigpending , +.Fn sigprocmask , +.Fn sigsuspend , +.Fn sleep , +.Fn sockatmark , +.Fn socket , +.Fn socketpair , +.Fn stat , +.Fn symlink , +.Fn symlinkat , +.Fn tcdrain , +.Fn tcflow , +.Fn tcflush , +.Fn tcgetattr , +.Fn tcgetpgrp , +.Fn tcsendbreak , +.Fn tcsetattr , +.Fn tcsetpgrp , +.Fn time , +.Fn times , +.Fn umask , +.Fn uname , +.Fn unlink , +.Fn unlinkat , +.Fn utime , +.Fn wait , +.Fn waitpid , +.Fn write . +.Pp +X/Open Systems Interfaces: +.Pp +.Fn sigpause , +.Fn sigset , +.Fn utimes . +.Pp +Realtime Interfaces: +.Pp +.Fn aio_error , +.Fn clock_gettime , +.Fn timer_getoverrun , +.Fn aio_return , +.Fn fdatasync , +.Fn sigqueue , +.Fn timer_gettime , +.Fn aio_suspend , +.Fn sem_post , +.Fn timer_settime . +.Pp +Base Interfaces not specified as async-signal safe by +.Tn POSIX : +.Pp +.Fn fpathconf , +.Fn pathconf , +.Fn sysconf . +.Pp +Base Interfaces not specified as async-signal safe by +.Tn POSIX , +but planned to be: +.Pp +.Fn ffs , +.Fn htonl , +.Fn htons , +.Fn memccpy , +.Fn memchr , +.Fn memcmp , +.Fn memcpy , +.Fn memmove , +.Fn memset , +.Fn ntohl , +.Fn ntohs , +.Fn stpcpy , +.Fn stpncpy , +.Fn strcat , +.Fn strchr , +.Fn strcmp , +.Fn strcpy , +.Fn strcspn , +.Fn strlen , +.Fn strncat , +.Fn strncmp , +.Fn strncpy , +.Fn strnlen , +.Fn strpbrk , +.Fn strrchr , +.Fn strspn , +.Fn strstr , +.Fn strtok_r , +.Fn wcpcpy , +.Fn wcpncpy , +.Fn wcscat , +.Fn wcschr , +.Fn wcscmp , +.Fn wcscpy , +.Fn wcscspn , +.Fn wcslen , +.Fn wcsncat , +.Fn wcsncmp , +.Fn wcsncpy , +.Fn wcsnlen , +.Fn wcspbrk , +.Fn wcsrchr , +.Fn wcsspn , +.Fn wcsstr , +.Fn wcstok , +.Fn wmemchr , +.Fn wmemcmp , +.Fn wmemcpy , +.Fn wmemmove , +.Fn wmemset . +.Pp +Extension Interfaces: +.Pp +.Fn accept4 , +.Fn bindat , +.Fn close_range , +.Fn closefrom , +.Fn connectat , +.Fn eaccess , +.Fn ffsl , +.Fn ffsll , +.Fn flock , +.Fn fls , +.Fn flsl , +.Fn flsll , +.Fn futimesat , +.Fn pipe2 , +.Fn strlcat . +.Fn strlcpy , +.Fn strsep . +.Pp +In addition, reading or writing +.Va errno +is async-signal safe. +.Pp +All functions not in the above lists are considered to be unsafe +with respect to signals. +That is to say, the behaviour of such +functions is undefined when they are called from a signal handler +that interrupted an unsafe function. +In general though, signal handlers should do little more than set a +flag; most other actions are not safe. +.Pp +Also, it is good practice to make a copy of the global variable +.Va errno +and restore it before returning from the signal handler. +This protects against the side effect of +.Va errno +being set by functions called from inside the signal handler. +.Sh RETURN VALUES +.Rv -std sigaction +.Sh EXAMPLES +There are three possible prototypes the handler may match: +.Bl -tag -offset indent -width short +.It Tn ANSI C : +.Ft void +.Fn handler int ; +.It Traditional BSD style: +.Ft void +.Fn handler int "int code" "struct sigcontext *scp" ; +.It Tn POSIX Dv SA_SIGINFO : +.Ft void +.Fn handler int "siginfo_t *info" "ucontext_t *uap" ; +.El +.Pp +The handler function should match the +.Dv SA_SIGINFO +prototype if the +.Dv SA_SIGINFO +bit is set in +.Va sa_flags . +It then should be pointed to by the +.Va sa_sigaction +member of +.Vt "struct sigaction" . +Note that you should not assign +.Dv SIG_DFL +or +.Dv SIG_IGN +this way. +.Pp +If the +.Dv SA_SIGINFO +flag is not set, the handler function should match +either the +.Tn ANSI C +or traditional +.Bx +prototype and be pointed to by +the +.Va sa_handler +member of +.Vt "struct sigaction" . +In practice, +.Fx +always sends the three arguments of the latter and since the +.Tn ANSI C +prototype is a subset, both will work. +The +.Va sa_handler +member declaration in +.Fx +include files is that of +.Tn ANSI C +(as required by +.Tn POSIX ) , +so a function pointer of a +.Bx Ns -style +function needs to be casted to +compile without warning. +The traditional +.Bx +style is not portable and since its capabilities +are a full subset of a +.Dv SA_SIGINFO +handler, +its use is deprecated. +.Pp +The +.Fa sig +argument is the signal number, one of the +.Dv SIG... +values from +.In signal.h . +.Pp +The +.Fa code +argument of the +.Bx Ns -style +handler and the +.Va si_code +member of the +.Fa info +argument to a +.Dv SA_SIGINFO +handler contain a numeric code explaining the +cause of the signal, usually one of the +.Dv SI_... +values from +.In sys/signal.h +or codes specific to a signal, i.e., one of the +.Dv FPE_... +values for +.Dv SIGFPE . +.Pp +The +.Fa scp +argument to a +.Bx Ns -style +handler points to an instance of +.Vt "struct sigcontext" . +.Pp +The +.Fa uap +argument to a +.Tn POSIX +.Dv SA_SIGINFO +handler points to an instance of +ucontext_t. +.Sh ERRORS +The +.Fn sigaction +system call +will fail and no new signal handler will be installed if one +of the following occurs: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa sig +argument +is not a valid signal number. +.It Bq Er EINVAL +An attempt is made to ignore or supply a handler for +.Dv SIGKILL +or +.Dv SIGSTOP . +.El +.Sh SEE ALSO +.Xr kill 1 , +.Xr kill 2 , +.Xr ptrace 2 , +.Xr setitimer 2 , +.Xr setrlimit 2 , +.Xr sigaltstack 2 , +.Xr sigpending 2 , +.Xr sigprocmask 2 , +.Xr sigsuspend 2 , +.Xr wait 2 , +.Xr fpsetmask 3 , +.Xr setjmp 3 , +.Xr siginfo 3 , +.Xr siginterrupt 3 , +.Xr sigsetops 3 , +.Xr ucontext 3 , +.Xr tty 4 +.Sh STANDARDS +The +.Fn sigaction +system call is expected to conform to +.St -p1003.1-90 . +The +.Dv SA_ONSTACK +and +.Dv SA_RESTART +flags are Berkeley extensions, +as are the signals, +.Dv SIGTRAP , +.Dv SIGEMT , +.Dv SIGBUS , +.Dv SIGSYS , +.Dv SIGURG , +.Dv SIGIO , +.Dv SIGXCPU , +.Dv SIGXFSZ , +.Dv SIGVTALRM , +.Dv SIGPROF , +.Dv SIGWINCH , +and +.Dv SIGINFO . +Those signals are available on most +.Bx Ns \-derived +systems. +The +.Dv SA_NODEFER +and +.Dv SA_RESETHAND +flags are intended for backwards compatibility with other operating +systems. +The +.Dv SA_NOCLDSTOP , +and +.Dv SA_NOCLDWAIT +.\" and +.\" SA_SIGINFO +flags are featuring options commonly found in other operating systems. +The flags are approved by +.St -susv2 , +along with the option to avoid zombie creation by ignoring +.Dv SIGCHLD . diff --git a/lib/libsys/sigaltstack.2 b/lib/libsys/sigaltstack.2 new file mode 100644 index 000000000000..388e1e58bd94 --- /dev/null +++ b/lib/libsys/sigaltstack.2 @@ -0,0 +1,159 @@ +.\" Copyright (c) 1983, 1991, 1992, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd May 6, 2010 +.Dt SIGALTSTACK 2 +.Os +.Sh NAME +.Nm sigaltstack +.Nd set and/or get signal stack context +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Bd -literal +typedef struct { + char *ss_sp; + size_t ss_size; + int ss_flags; +} stack_t; +.Ed +.Ft int +.Fn sigaltstack "const stack_t * restrict ss" "stack_t * restrict oss" +.Sh DESCRIPTION +The +.Fn sigaltstack +system call +allows defining an alternate stack on which signals +are to be processed for the current thread. +If +.Fa ss +is non-zero, +it specifies a pointer to and the size of a +.Em "signal stack" +on which to deliver signals. +When a signal's action indicates its handler +should execute on the signal stack (specified with a +.Xr sigaction 2 +system call), the system checks to see +if the thread is currently executing on that stack. +If the thread is not currently executing on the signal stack, +the system arranges a switch to the signal stack for the +duration of the signal handler's execution. +.Pp +An active stack cannot be modified. +.Pp +If +.Dv SS_DISABLE +is set in +.Fa ss_flags , +.Fa ss_sp +and +.Fa ss_size +are ignored and the signal stack will be disabled. +A disabled stack will cause all signals to be +taken on the regular user stack. +If the stack is later re-enabled then all signals that were specified +to be processed on an alternate stack will resume doing so. +.Pp +If +.Fa oss +is non-zero, the current signal stack state is returned. +The +.Fa ss_flags +field will contain the value +.Dv SS_ONSTACK +if the thread is currently on a signal stack and +.Dv SS_DISABLE +if the signal stack is currently disabled. +.Sh NOTES +The value +.Dv SIGSTKSZ +is defined to be the number of bytes/chars that would be used to cover +the usual case when allocating an alternate stack area. +The following code fragment is typically used to allocate an alternate stack. +.Bd -literal -offset indent +if ((sigstk.ss_sp = malloc(SIGSTKSZ)) == NULL) + /* error return */ +sigstk.ss_size = SIGSTKSZ; +sigstk.ss_flags = 0; +if (sigaltstack(&sigstk, NULL) < 0) + perror("sigaltstack"); +.Ed +An alternative approach is provided for programs with signal handlers +that require a specific amount of stack space other than the default size. +The value +.Dv MINSIGSTKSZ +is defined to be the number of bytes/chars that is required by +the operating system to implement the alternate stack feature. +In computing an alternate stack size, +programs should add +.Dv MINSIGSTKSZ +to their stack requirements to allow for the operating system overhead. +.Pp +Signal stacks are automatically adjusted for the direction of stack +growth and alignment requirements. +Signal stacks may or may not be protected by the hardware and +are not ``grown'' automatically as is done for the normal stack. +If the stack overflows and this space is not protected +unpredictable results may occur. +.Sh RETURN VALUES +.Rv -std sigaltstack +.Sh ERRORS +The +.Fn sigaltstack +system call +will fail and the signal stack context will remain unchanged +if one of the following occurs. +.Bl -tag -width Er +.It Bq Er EFAULT +Either +.Fa ss +or +.Fa oss +points to memory that is not a valid part of the process +address space. +.It Bq Er EPERM +An attempt was made to modify an active stack. +.It Bq Er EINVAL +The +.Fa ss_flags +field was invalid. +.It Bq Er ENOMEM +Size of alternate stack area is less than or equal to +.Dv MINSIGSTKSZ . +.El +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr setjmp 3 +.Sh HISTORY +The predecessor to +.Fn sigaltstack , +the +.Fn sigstack +system call, appeared in +.Bx 4.2 . diff --git a/lib/libsys/sigfastblock.2 b/lib/libsys/sigfastblock.2 new file mode 100644 index 000000000000..19d649e63db9 --- /dev/null +++ b/lib/libsys/sigfastblock.2 @@ -0,0 +1,164 @@ +.\" Copyright (c) 2016 The FreeBSD Foundation +.\" +.\" This documentation was written by +.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" 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 AUTHORS 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 AUTHORS 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. +.\" +.Dd December 13, 2019 +.Dt SIGFASTBLOCK 2 +.Os +.Sh NAME +.Nm sigfastblock +.Nd controls signals blocking with a simple memory write +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/signalvar.h +.Ft int +.Fn sigfastblock "int cmd" "void *ptr" +.Sh DESCRIPTION +.Bf -symbolic +This function is not intended for a direct usage by applications. +The functionality is provided for implementing some optimizations in +.Xr ld-elf.so.1 8 +and +.Lb libthr . +.Ef +.Pp +The function configures the kernel facility that allows a thread to +block asynchronous signals delivery with a single write to userspace +memory, avoiding overhead of system calls like +.Xr sigprocmask 2 +for establishing critical sections. +The C runtime uses it to optimize implementation of async-signal-safe +functionality. +.Pp +A thread might register a +.Dv sigblock +variable of type +.Vt int +as a location which is consulted by kernel when calculating the +blocked signal mask for delivery of asynchronous signals. +If the variable indicates that blocking is requested, then the kernel +effectively operates as if the mask containing all blockable signals was +supplied to +.Xr sigprocmask 2 . +.Pp +The variable is supposed to be modified only from the owning thread, +there is no way to guarantee visibility of update from other thread +to kernel when signals are delivered. +.Pp +Lower bits of the sigblock variable are reserved as flags, +which might be set or cleared by kernel at arbitrary moments. +Userspace code should use +.Xr atomic 9 +operations of incrementing and decrementing by +.Dv SIGFASTBLOCK_INC +quantity to recursively block or unblock signals delivery. +.Pp +If a signal would be delivered when unmasked, kernel might set the +.Dv SIGFASTBLOCK_PEND +.Dq pending signal +flag in the sigblock variable. +Userspace should perform +.Dv SIGFASTBLOCK_UNBLOCK +operation when clearing the variable if it notes the pending signal +bit is set, which would deliver the pending signals immediately. +Otherwise, signals delivery might be postponed. +.Pp +The +.Fa cmd +argument specifies one of the following operations: +.Bl -tag -width SIGFASTBLOCK_UNSETPTR +.It Dv SIGFASTBLOCK_SETPTR +Register the variable of type +.Vt int +at location pointed to by the +.Fa ptr +argument as sigblock variable for the calling thread. +.It Dv SIGFASTBLOCK_UNSETPTR +Unregister the currently registered sigblock location. +Kernel stops inferring the blocked mask from non-zero value of its +blocked count. +New location can be registered after previous one is deregistered. +.It Dv SIGFASTBLOCK_UNBLOCK +If there are pending signals which should be delivered to the calling +thread, they are delivered before returning from the call. +The sigblock variable should have zero blocking count, and indicate +that the pending signal exists. +Effectively this means that the variable should have the value +.Dv SIGFASTBLOCK_PEND . +.El +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The operation may fail with the following errors: +.Bl -tag -width Er +.It Bq Er EBUSY +The +.Dv SIGFASTBLOCK_SETPTR +attempted while the sigblock address was already registered. +The +.Dv SIGFASTBLOCK_UNBLOCK +was called while sigblock variable value is not equal to +.Dv SIGFASTBLOCK_PEND . +.It Bq Er EINVAL +The variable address passed to +.Dv SIGFASTBLOCK_SETPTR +is not aligned naturally. +The +.Dv SIGFASTBLOCK_UNSETPTR +operation was attempted without prior successful call to +.Dv SIGFASTBLOCK_SETPTR . +.It Bq Er EFAULT +Attempt to read or write to the sigblock variable failed. +Note that kernel generates the +.Dv SIGSEGV +signal if an attempt to read from the sigblock variable faulted +during implicit accesses from syscall entry. +.El +.Sh SEE ALSO +.Xr kill 2 , +.Xr signal 2 , +.Xr sigprocmask 2 , +.Xr libthr 3 , +.Xr ld-elf.so.1 8 +.Sh STANDARDS +The +.Nm +function is non-standard, although a similar functionality is a common +optimization provided by several other systems. +.Sh HISTORY +The +.Nm +function was introduced in +.Fx 13.0 . +.Sh BUGS +The +.Nm +symbol is currently not exported by libc, on purpose. +Consumers should either use the +.Dv __sys_fast_sigblock +symbol from the private libc namespace, or utilize +.Xr syscall 2 . diff --git a/lib/libsys/sigpending.2 b/lib/libsys/sigpending.2 new file mode 100644 index 000000000000..412f128778fb --- /dev/null +++ b/lib/libsys/sigpending.2 @@ -0,0 +1,74 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Berkeley Software Design, Inc. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd September 6, 2013 +.Dt SIGPENDING 2 +.Os +.Sh NAME +.Nm sigpending +.Nd get pending signals +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Ft int +.Fn sigpending "sigset_t *set" +.Sh DESCRIPTION +The +.Fn sigpending +system call returns a mask of the signals pending for delivery +to the calling thread or the calling process in the location indicated by +.Fa set . +Signals may be pending because they are currently masked, +or transiently before delivery (although the latter case is not +normally detectable). +.Sh RETURN VALUES +.Rv -std sigpending +.Sh ERRORS +The +.Fn sigpending +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EFAULT +The +.Fa set +argument specified an invalid address. +.El +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr sigprocmask 2 , +.Xr sigsuspend 2 , +.Xr sigsetops 3 +.Sh STANDARDS +The +.Fn sigpending +system call is expected to conform to +.St -p1003.1-90 . diff --git a/lib/libsys/sigprocmask.2 b/lib/libsys/sigprocmask.2 new file mode 100644 index 000000000000..351047a0fa66 --- /dev/null +++ b/lib/libsys/sigprocmask.2 @@ -0,0 +1,128 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd May 7, 2010 +.Dt SIGPROCMASK 2 +.Os +.Sh NAME +.Nm sigprocmask +.Nd manipulate current signal mask +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Ft int +.Fo sigprocmask +.Fa "int how" +.Fa "const sigset_t * restrict set" +.Fa "sigset_t * restrict oset" +.Fc +.Sh DESCRIPTION +The +.Fn sigprocmask +system call examines and/or changes the current signal mask (those signals +that are blocked from delivery). +Signals are blocked if they are members of the current signal mask set. +.Pp +If +.Fa set +is not null, the action of +.Fn sigprocmask +depends on the value of the +.Fa how +argument. +The signal mask is changed as a function of the specified +.Fa set +and the current mask. +The function is specified by +.Fa how +using one of the following values from +.In signal.h : +.Bl -tag -width SIG_UNBLOCK +.It Dv SIG_BLOCK +The new mask is the union of the current mask and the specified +.Fa set . +.It Dv SIG_UNBLOCK +The new mask is the intersection of the current mask +and the complement of the specified +.Fa set . +.It Dv SIG_SETMASK +The current mask is replaced by the specified +.Fa set . +.El +.Pp +If +.Fa oset +is not null, it is set to +the previous value of the signal mask. +When +.Fa set +is null, +the value of +.Fa how +is insignificant and the mask remains unset +providing a way to examine the signal mask without modification. +.Pp +The system +quietly disallows +.Dv SIGKILL +or +.Dv SIGSTOP +to be blocked. +.Pp +In threaded applications, +.Xr pthread_sigmask 3 +must be used instead of +.Fn sigprocmask . +.Sh RETURN VALUES +.Rv -std sigprocmask +.Sh ERRORS +The +.Fn sigprocmask +system call will fail and the signal mask will be unchanged if one +of the following occurs: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa how +argument +has a value other than those listed here. +.El +.Sh SEE ALSO +.Xr kill 2 , +.Xr sigaction 2 , +.Xr sigpending 2 , +.Xr sigsuspend 2 , +.Xr fpsetmask 3 , +.Xr pthread_sigmask 3 , +.Xr sigsetops 3 +.Sh STANDARDS +The +.Fn sigprocmask +system call is expected to +conform to +.St -p1003.1-90 . diff --git a/lib/libsys/sigqueue.2 b/lib/libsys/sigqueue.2 new file mode 100644 index 000000000000..2fac63610ac7 --- /dev/null +++ b/lib/libsys/sigqueue.2 @@ -0,0 +1,178 @@ +.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org> +.\" All rights reserved. +.\" +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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. +.\" +.Dd April 21, 2024 +.Dt SIGQUEUE 2 +.Os +.Sh NAME +.Nm sigqueue +.Nd "queue a signal to a process (REALTIME)" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Ft int +.Fn sigqueue "pid_t pid" "int signo" "const union sigval value" +.Sh DESCRIPTION +The +.Fn sigqueue +system call causes the signal specified by +.Fa signo +to be sent with the value specified by +.Fa value +to the process specified by +.Fa pid . +If +.Fa signo +is zero (the null signal), error checking is performed but +no signal is actually sent. +The null signal can be used to check the +validity of PID. +.Pp +The conditions required for a process to have permission to queue a +signal to another process are the same as for the +.Xr kill 2 +system call. +The +.Fn sigqueue +system call queues a signal to a single process specified by the +.Fa pid +argument. +.Pp +The +.Fn sigqueue +system call returns immediately. +If the resources were +available to queue the signal, the signal will be queued and sent to +the receiving process. +.Pp +If the value of +.Fa pid +causes +.Fa signo +to be generated for the sending process, and if +.Fa signo +is not blocked for the calling thread and if no other thread has +.Fa signo +unblocked or is waiting in a +.Fn sigwait +system call for +.Fa signo , +either +.Fa signo +or at least the pending, unblocked signal will be delivered to the +calling thread before +.Fn sigqueue +returns. +Should any multiple pending signals in the range +.Dv SIGRTMIN +to +.Dv SIGRTMAX +be selected for delivery, it is the lowest numbered +one. +The selection order between realtime and non-realtime signals, or +between multiple pending non-realtime signals, is unspecified. +.Pp +As a +.Fx +extension, the value of +.Fa signo +can be or-ed with the following flags: +.Bl -tag -width __SIGQUEUE_TID +.It Dv __SIGQUEUE_TID +The +.Fa pid +parameter is the thread identifier of a thread in the current process, +and the specified signal is queued into the specified thread' queue. +.El +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn sigqueue +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +No resources are available to queue the signal. +The process has already +queued +.Brq Dv SIGQUEUE_MAX +signals that are still pending at the receiver(s), +or a system-wide resource limit has been exceeded. +.It Bq Er EINVAL +The value of the +.Fa signo +argument is an invalid or unsupported signal number. +.It Bq Er EPERM +The process does not have the appropriate privilege to send the signal +to the receiving process. +.It Bq Er ESRCH +The process +.Fa pid +does not exist. +.It Bq Er ESRCH +The thread with id +.Fa pid +does not exist in the current process. +.El +.Sh SEE ALSO +.Xr kill 2 , +.Xr sigaction 2 , +.Xr sigpending 2 , +.Xr sigsuspend 2 , +.Xr sigtimedwait 2 , +.Xr sigwait 2 , +.Xr sigwaitinfo 2 , +.Xr pause 3 , +.Xr pthread_sigmask 3 , +.Xr siginfo 3 +.Sh STANDARDS +The +.Fn sigqueue +system call conforms to +.St -p1003.1-2004 . +.Sh HISTORY +Support for +.Tn POSIX +realtime signal queue first appeared in +.Fx 7.0 . +.Sh CAVEATS +When using +.Nm +to send signals to a process which might have a different ABI +(for instance, one is 32-bit and the other 64-bit), +the +.Va sival_int +member of +.Fa value +can be delivered reliably, but the +.Va sival_ptr +may be truncated in endian dependent ways and must not be relied on. +Further, many pointer integrity schemes disallow sending pointers to other +processes, and this technique should not be used in programs intended to +be portable. diff --git a/lib/libsys/sigreturn.2 b/lib/libsys/sigreturn.2 new file mode 100644 index 000000000000..4effeaa5abc7 --- /dev/null +++ b/lib/libsys/sigreturn.2 @@ -0,0 +1,86 @@ +.\" Copyright (c) 1985, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd September 6, 2013 +.Dt SIGRETURN 2 +.Os +.Sh NAME +.Nm sigreturn +.Nd return from signal +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Ft int +.Fn sigreturn "const ucontext_t *scp" +.Sh DESCRIPTION +The +.Fn sigreturn +system call +allows users to atomically unmask, switch stacks, +and return from a signal context. +The thread's signal mask and stack status are +restored from the context structure pointed to by +.Fa scp . +The system call does not return; +the users stack pointer, frame pointer, argument pointer, +and processor status longword are restored from the context. +Execution resumes at the specified pc. +This system call is used by the trampoline code and +.Xr longjmp 3 +when returning from a signal to the previously executing program. +.Sh RETURN VALUES +If successful, the system call does not return. +Otherwise, a value of -1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn sigreturn +system call +will fail and the thread context will remain unchanged +if one of the following occurs. +.Bl -tag -width Er +.It Bq Er EFAULT +The +.Fa scp +argument +points to memory that is not a valid part of the process +address space. +.It Bq Er EINVAL +The process status longword is invalid or would improperly +raise the privilege level of the process. +.El +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr setjmp 3 , +.Xr ucontext 3 +.Sh HISTORY +The +.Fn sigreturn +system call appeared in +.Bx 4.3 . diff --git a/lib/libsys/sigstack.2 b/lib/libsys/sigstack.2 new file mode 100644 index 000000000000..3e60d4dace6a --- /dev/null +++ b/lib/libsys/sigstack.2 @@ -0,0 +1,47 @@ +.\" Copyright (c) 1983, 1992, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd June 4, 1993 +.Dt SIGSTACK 2 +.Os +.Sh NAME +.Nm sigstack +.Nd set and/or get signal stack context +.Sh LIBRARY +.Lb libc +.Sh DESCRIPTION +The +.Fn sigstack +function has been deprecated in favor of the interface described in +.Xr sigaltstack 2 . +.Sh SEE ALSO +.Xr sigaltstack 2 +.Sh HISTORY +The +.Fn sigstack +system call appeared in +.Bx 4.2 . diff --git a/lib/libsys/sigsuspend.2 b/lib/libsys/sigsuspend.2 new file mode 100644 index 000000000000..717bd3ff6858 --- /dev/null +++ b/lib/libsys/sigsuspend.2 @@ -0,0 +1,82 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd August 16, 2013 +.Dt SIGSUSPEND 2 +.Os +.Sh NAME +.Nm sigsuspend +.Nd atomically release blocked signals and wait for interrupt +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Ft int +.Fn sigsuspend "const sigset_t *sigmask" +.Sh DESCRIPTION +The +.Fn sigsuspend +system call +temporarily changes the blocked signal mask to the set to which +.Fa sigmask +points, +and then waits for a signal to arrive; +on return the previous set of masked signals is restored. +The signal mask set +is usually empty to indicate that all +signals are to be unblocked for the duration of the call. +.Pp +In normal usage, a signal is blocked using +.Xr sigprocmask 2 +to begin a critical section, variables modified on the occurrence +of the signal are examined to determine that there is no work +to be done, and the process pauses awaiting work by using +.Fn sigsuspend +with the previous mask returned by +.Xr sigprocmask 2 . +.Sh RETURN VALUES +The +.Fn sigsuspend +system call +always terminates by being interrupted, returning -1 with +.Va errno +set to +.Er EINTR . +.Sh SEE ALSO +.Xr pselect 2 , +.Xr sigaction 2 , +.Xr sigpending 2 , +.Xr sigprocmask 2 , +.Xr sigtimedwait 2 , +.Xr sigwait 2 , +.Xr sigwaitinfo 2 , +.Xr sigsetops 3 +.Sh STANDARDS +The +.Fn sigsuspend +system call is expected to conform to +.St -p1003.1-90 . diff --git a/lib/libsys/sigwait.2 b/lib/libsys/sigwait.2 new file mode 100644 index 000000000000..cd8a6bd026d4 --- /dev/null +++ b/lib/libsys/sigwait.2 @@ -0,0 +1,122 @@ +.\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>. +.\" All rights reserved. +.\" +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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. +.\" +.Dd September 6, 2013 +.Dt SIGWAIT 2 +.Os +.Sh NAME +.Nm sigwait +.Nd select a set of signals +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Ft int +.Fn sigwait "const sigset_t * restrict set" "int * restrict sig" +.Sh DESCRIPTION +The +.Fn sigwait +system call selects a set of signals, specified by +.Fa set . +If none of the selected signals are pending, +.Fn sigwait +waits until one or more of the selected signals has been generated. +Then +.Fn sigwait +atomically clears one of the selected signals from the set of pending signals +(for the process or for the current thread) and sets the location pointed to by +.Fa sig +to the signal number that was cleared. +.Pp +The signals specified by +.Fa set +should be blocked at the time of the call to +.Fn sigwait . +.Pp +If more than one thread is using +.Fn sigwait +to wait for the same signal, no more than one of these threads will return from +.Fn sigwait +with the signal number. +If more than a single thread is blocked in +.Fn sigwait +for a signal when that signal is generated for the process, it is unspecified +which of the waiting threads returns from +.Fn sigwait . +If the signal is generated for a specific thread, as by +.Fn pthread_kill , +only that thread will return. +.Pp +Should any of the multiple pending signals in the range +.Dv SIGRTMIN +to +.Dv SIGRTMAX +be +selected, it will be the lowest numbered one. +The selection order between realtime +and non-realtime signals, or between multiple pending non-realtime signals, +is unspecified. +.Sh IMPLEMENTATION NOTES +The +.Fn sigwait +function is implemented as a wrapper around the +.Fn __sys_sigwait +system call, which retries the call on +.Er EINTR +error. +.Sh RETURN VALUES +If successful, +.Fn sigwait +returns 0 and sets the location pointed to by +.Fa sig +to the cleared signal number. +Otherwise, an error number is returned. +.Sh ERRORS +The +.Fn sigwait +system call will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa set +argument +specifies one or more invalid signal numbers. +.El +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr sigpending 2 , +.Xr sigqueue 2 , +.Xr sigsuspend 2 , +.Xr sigtimedwait 2 , +.Xr sigwaitinfo 2 , +.Xr pause 3 , +.Xr pthread_sigmask 3 +.Sh STANDARDS +The +.Fn sigwait +function conforms to +.St -p1003.1-96 . diff --git a/lib/libsys/sigwaitinfo.2 b/lib/libsys/sigwaitinfo.2 new file mode 100644 index 000000000000..10fc29ce39a7 --- /dev/null +++ b/lib/libsys/sigwaitinfo.2 @@ -0,0 +1,213 @@ +.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org> +.\" All rights reserved. +.\" +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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. +.\" +.Dd April 21, 2022 +.Dt SIGTIMEDWAIT 2 +.Os +.Sh NAME +.Nm sigtimedwait , sigwaitinfo +.Nd "wait for queued signals (REALTIME)" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Ft int +.Fo sigtimedwait +.Fa "const sigset_t *restrict set" "siginfo_t *restrict info" +.Fa "const struct timespec *restrict timeout" +.Fc +.Ft int +.Fn sigwaitinfo "const sigset_t * restrict set" "siginfo_t * restrict info" +.Sh DESCRIPTION +The +.Fn sigtimedwait +system call is equivalent to +.Fn sigwaitinfo +except that if none of the signals specified by +.Fa set +are pending, +.Fn sigtimedwait +waits for the time interval specified in the +.Vt timespec +structure referenced by +.Fa timeout . +If the +.Vt timespec +structure pointed to by +.Fa timeout +is zero-valued and if none of the signals specified by +.Fa set +are pending, then +.Fn sigtimedwait +returns immediately with an error. +If +.Fa timeout +is the +.Dv NULL +pointer, +.Fn sigtimedwait +blocks indefinitely. +.Dv CLOCK_MONOTONIC +clock is used to measure the time interval specified by the +.Fa timeout +argument. +.Pp +The +.Fn sigwaitinfo +system call selects the pending signal from the set specified by +.Fa set . +Should any of multiple pending signals in the range +.Dv SIGRTMIN +to +.Dv SIGRTMAX +be selected, it shall be the lowest numbered one. +The +selection order between realtime and non-realtime signals, or +between multiple pending non-realtime signals, is unspecified. +If no signal in +.Fa set +is pending at the time of the call, the calling thread +is suspended until one or more signals in +.Fa set +become pending or until it is interrupted by an unblocked, caught signal. +.Pp +The +.Fn sigwaitinfo +system call is equivalent to the +.Fn sigwait +system call if the +.Fa info +argument is +.Dv NULL . +If the +.Fa info +argument is +.Pf non- Dv NULL , +the +.Fn sigwaitinfo +function is equivalent to +.Fn sigwait , +except that the selected signal number shall be stored in the +.Va si_signo +member, and the cause of the signal shall be stored in the +.Va si_code +member. +Besides this, the +.Fn sigwaitinfo +and +.Fn sigtimedwait +system calls may return +.Er EINTR +if interrupted by signal, which is not allowed for the +.Fn sigwait +function. +.Pp +If any value is queued to the selected signal, the first such queued +value is dequeued and, if the info argument is +.Pf non- Dv NULL , +the value is stored in the +.Va si_value +member of +.Fa info . +The system resource used to queue the signal +is released and returned to the system for other use. +If no value is queued, +the content of the +.Va si_value +member is zero-valued. +If no further signals are +queued for the selected signal, the pending indication for that signal +is reset. +.Sh RETURN VALUES +Upon successful completion (that is, one of the signals specified by +.Fa set +is pending or is generated) +.Fn sigwaitinfo +and +.Fn sigtimedwait +return the selected signal number. +Otherwise, the functions return a value of \-1 +and set the global variable +.Va errno +to indicate the error. +.Sh ERRORS +The +.Fn sigtimedwait +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +No signal specified by set was generated within the specified timeout period. +.El +.Pp +The +.Fn sigtimedwait +and +.Fn sigwaitinfo +system calls fail if: +.Bl -tag -width Er +.It Bq Er EINTR +The wait was interrupted by an unblocked, caught signal. +.El +.Pp +The +.Fn sigtimedwait +system call may also fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa timeout +argument specified a +.Va tv_nsec +value less than zero or greater than or equal +to 1000 million. +Kernel only checks for this error if no signal is pending in set and it +is necessary to wait. +.El +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr sigpending 2 , +.Xr sigqueue 2 , +.Xr sigsuspend 2 , +.Xr sigwait 2 , +.Xr pause 3 , +.Xr pthread_sigmask 3 , +.Xr siginfo 3 +.Sh STANDARDS +The +.Fn sigtimedwait +and +.Fn sigwaitinfo +system calls conform to +.St -p1003.1-96 . +POSIX +leaves the behavior of +.Fn sigtimedwait +with a +.Dv NULL +.Fa timeout +pointer unspecified. diff --git a/lib/libsys/sleep.3 b/lib/libsys/sleep.3 new file mode 100644 index 000000000000..b47cdaa4a59a --- /dev/null +++ b/lib/libsys/sleep.3 @@ -0,0 +1,80 @@ +.\" Copyright (c) 1986, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd February 13, 1998 +.Dt SLEEP 3 +.Os +.Sh NAME +.Nm sleep +.Nd suspend thread execution for an interval measured in seconds +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft unsigned int +.Fn sleep "unsigned int seconds" +.Sh DESCRIPTION +The +.Fn sleep +function suspends execution of the calling thread until either +.Fa seconds +seconds have elapsed or a signal is delivered to the thread and its +action is to invoke a signal-catching function or to terminate the +thread or process. +System activity may lengthen the sleep by an indeterminate amount. +.Pp +This function is implemented using +.Xr nanosleep 2 +by pausing for +.Fa seconds +seconds or until a signal occurs. +Consequently, in this implementation, +sleeping has no effect on the state of process timers, +and there is no special handling for SIGALRM. +.Sh RETURN VALUES +If the +.Fn sleep +function returns because the requested time has elapsed, the value +returned will be zero. +If the +.Fn sleep +function returns due to the delivery of a signal, the value returned +will be the unslept amount (the requested time minus the time actually +slept) in seconds. +.Sh SEE ALSO +.Xr nanosleep 2 , +.Xr usleep 3 +.Sh STANDARDS +The +.Fn sleep +function conforms to +.St -p1003.1-90 . +.Sh HISTORY +A +.Fn sleep +function appeared in +.At v7 . diff --git a/lib/libsys/socket.2 b/lib/libsys/socket.2 new file mode 100644 index 000000000000..b211611c6354 --- /dev/null +++ b/lib/libsys/socket.2 @@ -0,0 +1,358 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd May 17, 2025 +.Dt SOCKET 2 +.Os +.Sh NAME +.Nm socket +.Nd create an endpoint for communication +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/socket.h +.Ft int +.Fn socket "int domain" "int type" "int protocol" +.Sh DESCRIPTION +The +.Fn socket +system call +creates an endpoint for communication and returns a descriptor. +.Pp +The +.Fa domain +argument specifies a communications domain within which +communication will take place; this selects the protocol family +which should be used. +These families are defined in the include file +.In sys/socket.h . +The currently understood formats are: +.Pp +.Bd -literal -offset indent -compact +PF_LOCAL Host-internal protocols (alias for PF_UNIX), +PF_UNIX Host-internal protocols, +PF_INET Internet version 4 protocols, +PF_INET6 Internet version 6 protocols, +PF_DIVERT Firewall packet diversion/re-injection, +PF_ROUTE Internal routing protocol, +PF_KEY Internal key-management function, +PF_NETGRAPH Netgraph sockets, +PF_NETLINK Netlink protocols, +PF_BLUETOOTH Bluetooth protocols, +PF_INET_SDP OFED socket direct protocol (IPv4), +AF_HYPERV HyperV sockets +.Ed +.Pp +Each protocol family is connected to an address family, which has the +same name except that the prefix is +.Dq Dv AF_ +in place of +.Dq Dv PF_ . +Other protocol families may be also defined, beginning with +.Dq Dv PF_ , +with corresponding address families. +.Pp +The socket has the indicated +.Fa type , +which specifies the semantics of communication. +Currently +defined types are: +.Pp +.Bd -literal -offset indent -compact +SOCK_STREAM Stream socket, +SOCK_DGRAM Datagram socket, +SOCK_RAW Raw-protocol interface, +SOCK_SEQPACKET Sequenced packet stream +.Ed +.Pp +A +.Dv SOCK_STREAM +type provides sequenced, reliable, +two-way connection based byte streams. +An out-of-band data transmission mechanism may be supported. +A +.Dv SOCK_DGRAM +socket supports +datagrams (connectionless, unreliable messages of +a fixed (typically small) maximum length). +A +.Dv SOCK_SEQPACKET +socket may provide a sequenced, reliable, +two-way connection-based data transmission path for datagrams +of fixed maximum length; a consumer may be required to read +an entire packet with each read system call. +This facility may have protocol-specific properties. +.Dv SOCK_RAW +sockets provide access to internal network protocols and interfaces. +The +.Dv SOCK_RAW +type is available only to the super-user and is described in +.Xr ip 4 +and +.Xr ip6 4 . +.Pp +Additionally, the following flags are allowed in the +.Fa type +argument: +.Pp +.Bd -literal -offset indent -compact +SOCK_CLOEXEC Set close-on-exec on the new descriptor, +SOCK_CLOFORK Set close-on-fork on the new descriptor, +SOCK_NONBLOCK Set non-blocking mode on the new socket +.Ed +.Pp +The +.Fa protocol +argument +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. +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 +particular to the +.Dq "communication domain" +in which communication +is to take place; see +.Xr protocols 5 . +.Pp +The +.Fa protocol +argument may be set to zero (0) to request the default +implementation of a socket type for the protocol, if any. +.Pp +Sockets of type +.Dv SOCK_STREAM +are full-duplex byte streams, similar +to pipes. +A stream socket must be in a +.Em connected +state before any data may be sent or received +on it. +A connection to another socket is created with a +.Xr connect 2 +system call. +Once connected, data may be transferred using +.Xr read 2 +and +.Xr write 2 +calls or some variant of the +.Xr send 2 +and +.Xr recv 2 +functions. +(Some protocol families, such as the Internet family, +support the notion of an +.Dq implied connect , +which permits data to be sent piggybacked onto a connect operation by +using the +.Xr sendto 2 +system call.) +When a session has been completed a +.Xr close 2 +may be performed. +Out-of-band data may also be transmitted as described in +.Xr send 2 +and received as described in +.Xr recv 2 . +.Pp +The communications protocols used to implement a +.Dv 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 broken and calls +will indicate an error with +-1 returns and with +.Er ETIMEDOUT +as the specific code +in the global variable +.Va errno . +The protocols optionally keep sockets +.Dq warm +by forcing transmissions +roughly every minute in the absence of other activity. +An error is then indicated if no response can be +elicited on an otherwise +idle connection for an extended period (e.g.\& 5 minutes). +By default, a +.Dv SIGPIPE +signal is raised if a process sends +on a broken stream, but this behavior may be inhibited via +.Xr setsockopt 2 . +.Pp +.Dv SOCK_SEQPACKET +sockets employ the same system calls +as +.Dv SOCK_STREAM +sockets. +The only difference +is that +.Xr read 2 +calls will return only the amount of data requested, +and any remaining in the arriving packet will be discarded. +.Pp +.Dv SOCK_DGRAM +and +.Dv SOCK_RAW +sockets allow sending of datagrams to correspondents +named in +.Xr send 2 +calls. +Datagrams are generally received with +.Xr recvfrom 2 , +which returns the next datagram with its return address. +.Pp +An +.Xr fcntl 2 +system call can be used to specify a process group to receive +a +.Dv SIGURG +signal when the out-of-band data arrives. +It may also enable non-blocking I/O +and asynchronous notification of I/O events +via +.Dv SIGIO . +.Pp +The operation of sockets is controlled by socket level +.Em options . +These options are defined in the file +.In sys/socket.h . +The +.Xr setsockopt 2 +and +.Xr getsockopt 2 +system calls are used to set and get options, respectively. +.Sh RETURN VALUES +A -1 is returned if an error occurs, otherwise the return +value is a descriptor referencing the socket. +.Sh ERRORS +The +.Fn socket +system call fails if: +.Bl -tag -width Er +.It Bq Er EACCES +Permission to create a socket of the specified type and/or protocol +is denied. +.It Bq Er EAFNOSUPPORT +The address family (domain) is not supported or the +specified domain is not supported by this protocol family. +.It Bq Er EMFILE +The per-process descriptor table is full. +.It Bq Er ENFILE +The system file table is full. +.It Bq Er ENOBUFS +Insufficient buffer space is available. +The socket cannot be created until sufficient resources are freed. +.It Bq Er EPERM +User has insufficient privileges to carry out the requested operation. +.It Bq Er EPROTONOSUPPORT +The protocol type or the specified protocol is not supported +within this domain. +.It Bq Er EPROTOTYPE +The socket type is not supported by the protocol. +.El +.Sh SEE ALSO +.Xr accept 2 , +.Xr bind 2 , +.Xr connect 2 , +.Xr getpeername 2 , +.Xr getsockname 2 , +.Xr getsockopt 2 , +.Xr ioctl 2 , +.Xr listen 2 , +.Xr read 2 , +.Xr recv 2 , +.Xr select 2 , +.Xr send 2 , +.Xr shutdown 2 , +.Xr socketpair 2 , +.Xr write 2 , +.Xr CMSG_DATA 3 , +.Xr getprotoent 3 , +.Xr divert 4 , +.Xr ip 4 , +.Xr ip6 4 , +.Xr netgraph 4 , +.Xr protocols 5 +.Rs +.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial" +.%B PS1 +.%N 7 +.Re +.Rs +.%T "BSD Interprocess Communication Tutorial" +.%B PS1 +.%N 8 +.Re +.Sh STANDARDS +The +.Fn socket +function conforms to +.St -p1003.1-2008 . +The +.Tn POSIX +standard specifies only the +.Dv AF_INET , +.Dv AF_INET6 , +and +.Dv AF_UNIX +constants for address families, and requires the use of +.Dv AF_* +constants for the +.Fa domain +argument of +.Fn socket . +The +.Dv SOCK_CLOEXEC +and +.Dv SOCK_CLOFORK +flags are expected to conform to +.St -p1003.1-2024 . +.Tn POSIX +standard. +The +.Dv SOCK_RDM +.Fa type , +the +.Dv PF_* +constants, and other address families are +.Fx +extensions. +.Sh HISTORY +The +.Fn socket +system call appeared in +.Bx 4.2 . +.Pp +The +.Dv SOCK_CLOFORK +flag appeared in +.Fx 15.0 . diff --git a/lib/libsys/socketpair.2 b/lib/libsys/socketpair.2 new file mode 100644 index 000000000000..60dec74f9cc2 --- /dev/null +++ b/lib/libsys/socketpair.2 @@ -0,0 +1,105 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd May 17, 2025 +.Dt SOCKETPAIR 2 +.Os +.Sh NAME +.Nm socketpair +.Nd create a pair of connected sockets +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.Ft int +.Fn socketpair "int domain" "int type" "int protocol" "int *sv" +.Sh DESCRIPTION +The +.Fn socketpair +system call creates an unnamed pair of connected sockets in +the specified communications +.Fa domain , +of the specified +.Fa type , +and using the optionally specified +.Fa protocol . +The descriptors used in referencing the new sockets +are returned in +.Fa sv Ns [0] +and +.Fa sv Ns [1] . +The two sockets are indistinguishable. +.Pp +The +.Dv SOCK_CLOEXEC , +.Dv SOCK_CLOFORK +and +.Dv SOCK_NONBLOCK +flags in the +.Fa type +argument apply to both descriptors. +.Sh RETURN VALUES +.Rv -std socketpair +.Sh ERRORS +The call succeeds unless: +.Bl -tag -width Er +.It Bq Er EMFILE +Too many descriptors are in use by this process. +.It Bq Er EAFNOSUPPORT +The specified address family is not supported on this machine. +.It Bq Er EPROTONOSUPPORT +The specified protocol is not supported on this machine. +.It Bq Er EOPNOTSUPP +The specified protocol does not support creation of socket pairs. +.It Bq Er EFAULT +The address +.Fa sv +does not specify a valid part of the +process address space. +.El +.Sh SEE ALSO +.Xr pipe 2 , +.Xr read 2 , +.Xr socket 2 , +.Xr write 2 +.Sh STANDARDS +The +.Fn socketpair +system call conforms to +.St -p1003.1-2001 +and +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn socketpair +system call appeared in +.Bx 4.2 . +.Sh BUGS +This call is currently implemented only for the +.Ux +domain. diff --git a/lib/libsys/stat.2 b/lib/libsys/stat.2 new file mode 100644 index 000000000000..bd9005710147 --- /dev/null +++ b/lib/libsys/stat.2 @@ -0,0 +1,489 @@ +.\" Copyright (c) 1980, 1991, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd March 30, 2021 +.Dt STAT 2 +.Os +.Sh NAME +.Nm stat , +.Nm lstat , +.Nm fstat , +.Nm fstatat +.Nd get file status +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/stat.h +.Ft int +.Fn stat "const char * restrict path" "struct stat * restrict sb" +.Ft int +.Fn lstat "const char * restrict path" "struct stat * restrict sb" +.Ft int +.Fn fstat "int fd" "struct stat *sb" +.Ft int +.Fn fstatat "int fd" "const char *path" "struct stat *sb" "int flag" +.Sh DESCRIPTION +The +.Fn stat +system call obtains information about the file pointed to by +.Fa path . +Read, write or execute +permission of the named file is not required, but all directories +listed in the path name leading to the file must be searchable. +.Pp +The +.Fn lstat +system call is like +.Fn stat +except when the named file is a symbolic link, +in which case +.Fn lstat +returns information about the link, +while +.Fn stat +returns information about the file the link references. +.Pp +The +.Fn fstat +system call obtains the same information about an open file +known by the file descriptor +.Fa fd . +.Pp +The +.Fn fstatat +system call is equivalent to +.Fn stat +and +.Fn lstat +except when the +.Fa path +specifies a relative path. +For +.Fn fstatat +and relative +.Fa path , +the status is retrieved from a file relative to +the directory associated with the file descriptor +.Fa fd +instead of the current working directory. +.Pp +The values for the +.Fa flag +are constructed by a bitwise-inclusive OR of flags from this list, +defined in +.In fcntl.h : +.Bl -tag -width indent +.It Dv AT_SYMLINK_NOFOLLOW +If +.Fa path +names a symbolic link, the status of the symbolic link is returned. +.It Dv AT_RESOLVE_BENEATH +Only walk paths below the starting directory. +See the description of the +.Dv O_RESOLVE_BENEATH +flag in the +.Xr open 2 +manual page. +.It Dv AT_EMPTY_PATH +If the +.Fa path +argument is an empty string, operate on the file or directory +referenced by the descriptor +.Fa fd . +If +.Fa fd +is equal to +.Dv AT_FDCWD , +operate on the current working directory. +.El +.Pp +If +.Fn fstatat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is +identical to a call to +.Fn stat +or +.Fn lstat +respectively, depending on whether or not the +.Dv AT_SYMLINK_NOFOLLOW +bit is set in +.Fa flag . +.Pp +When +.Fn fstatat +is called with an absolute +.Fa path , +it ignores the +.Fa fd +argument. +.Pp +The +.Fa sb +argument is a pointer to a +.Vt stat +structure +as defined by +.In sys/stat.h +and into which information is placed concerning the file. +.Pp +The fields of +.Vt "struct stat" +related to the file system are: +.Bl -tag -width ".Va st_nlink" +.It Va st_dev +Numeric ID of the device containing the file. +.It Va st_ino +The file's inode number. +.It Va st_nlink +Number of hard links to the file. +.It Va st_flags +Flags enabled for the file. +See +.Xr chflags 2 +for the list of flags and their description. +.El +.Pp +The +.Va st_dev +and +.Va st_ino +fields together identify the file uniquely within the system. +.Pp +The time-related fields of +.Vt "struct stat" +are: +.Bl -tag -width ".Va st_birthtim" +.It Va st_atim +Time when file data was last accessed. +Changed implicitly by syscalls such as +.Xr read 2 +and +.Xr readv 2 , +and explicitly by +.Xr utimes 2 . +.It Va st_mtim +Time when file data was last modified. +Changed implicitly by syscalls such as +.Xr truncate 2 , +.Xr write 2 , +and +.Xr writev 2 , +and explicitly by +.Xr utimes 2 . +Also, any syscall which modifies directory content changes the +.Va st_mtim +for the affected directory. +For instance, +.Xr creat 2 , +.Xr mkdir 2 , +.Xr rename 2 , +.Xr link 2 , +and +.Xr unlink 2 . +.It Va st_ctim +Time when file status was last changed (inode data modification). +Changed implicitly by any syscall that affects file metadata, including +.Va st_mtim , +such as +.Xr chflags 2 , +.Xr chmod 2 , +.Xr chown 2 , +.Xr truncate 2 , +.Xr utimes 2 , +and +.Xr write 2 . +Also, any syscall which modifies directory content changes the +.Va st_ctim +for the affected directory. +For instance, +.Xr creat 2 , +.Xr mkdir 2 , +.Xr rename 2 , +.Xr link 2 , +and +.Xr unlink 2 . +.It Va st_birthtim +Time when the inode was created. +.El +.Pp +These time-related macros are defined for compatibility: +.Bd -literal +#define st_atime st_atim.tv_sec +#define st_mtime st_mtim.tv_sec +#define st_ctime st_ctim.tv_sec +#ifndef _POSIX_SOURCE +#define st_birthtime st_birthtim.tv_sec +#endif + +#ifndef _POSIX_SOURCE +#define st_atimespec st_atim +#define st_mtimespec st_mtim +#define st_ctimespec st_ctim +#define st_birthtimespec st_birthtim +#endif +.Ed +.Pp +Size-related fields of the +.Vt "struct stat" +are: +.Bl -tag -width ".Va st_blksize" +.It Va st_size +File size in bytes. +.It Va st_blksize +Optimal I/O block size for the file. +.It Va st_blocks +Actual number of blocks allocated for the file in 512-byte units. +As short symbolic links are stored in the inode, this number may +be zero. +.El +.Pp +The access-related fields of +.Vt "struct stat" +are: +.Bl -tag -width ".Va st_mode" +.It Va st_uid +User ID of the file's owner. +.It Va st_gid +Group ID of the file. +.It Va st_mode +Status of the file (see below). +.El +.Pp +The status information word +.Fa st_mode +has these bits: +.Bd -literal +#define S_IFMT 0170000 /* type of file mask */ +#define S_IFIFO 0010000 /* named pipe (fifo) */ +#define S_IFCHR 0020000 /* character special */ +#define S_IFDIR 0040000 /* directory */ +#define S_IFBLK 0060000 /* block special */ +#define S_IFREG 0100000 /* regular */ +#define S_IFLNK 0120000 /* symbolic link */ +#define S_IFSOCK 0140000 /* socket */ +#define S_IFWHT 0160000 /* whiteout */ +#define S_ISUID 0004000 /* set user id on execution */ +#define S_ISGID 0002000 /* set group id on execution */ +#define S_ISVTX 0001000 /* save swapped text even after use */ +#define S_IRWXU 0000700 /* RWX mask for owner */ +#define S_IRUSR 0000400 /* read permission, owner */ +#define S_IWUSR 0000200 /* write permission, owner */ +#define S_IXUSR 0000100 /* execute/search permission, owner */ +#define S_IRWXG 0000070 /* RWX mask for group */ +#define S_IRGRP 0000040 /* read permission, group */ +#define S_IWGRP 0000020 /* write permission, group */ +#define S_IXGRP 0000010 /* execute/search permission, group */ +#define S_IRWXO 0000007 /* RWX mask for other */ +#define S_IROTH 0000004 /* read permission, other */ +#define S_IWOTH 0000002 /* write permission, other */ +#define S_IXOTH 0000001 /* execute/search permission, other */ +.Ed +.Pp +For a list of access modes, see +.In sys/stat.h , +.Xr access 2 +and +.Xr chmod 2 . +These macros are available to test whether a +.Va st_mode +value passed in the +.Fa m +argument corresponds to a file of the specified type: +.Bl -tag -width ".Fn S_ISFIFO m" +.It Fn S_ISBLK m +Test for a block special file. +.It Fn S_ISCHR m +Test for a character special file. +.It Fn S_ISDIR m +Test for a directory. +.It Fn S_ISFIFO m +Test for a pipe or FIFO special file. +.It Fn S_ISLNK m +Test for a symbolic link. +.It Fn S_ISREG m +Test for a regular file. +.It Fn S_ISSOCK m +Test for a socket. +.It Fn S_ISWHT m +Test for a whiteout. +.El +.Pp +The macros evaluate to a non-zero value if the test is true +or to the value 0 if the test is false. +.Sh RETURN VALUES +.Rv -std +.Sh COMPATIBILITY +Previous versions of the system used different types for the +.Va st_dev , +.Va st_uid , +.Va st_gid , +.Va st_rdev , +.Va st_size , +.Va st_blksize +and +.Va st_blocks +fields. +.Sh ERRORS +The +.Fn stat +and +.Fn lstat +system calls will fail if: +.Bl -tag -width Er +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er EFAULT +The +.Fa sb +or +.Fa path +argument +points to an invalid address. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named file does not exist. +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er EOVERFLOW +The file size in bytes cannot be +represented correctly in the structure pointed to by +.Fa sb . +.El +.Pp +The +.Fn fstat +system call will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument +is not a valid open file descriptor. +.It Bq Er EFAULT +The +.Fa sb +argument +points to an invalid address. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.It Bq Er EOVERFLOW +The file size in bytes cannot be +represented correctly in the structure pointed to by +.Fa sb . +.El +.Pp +In addition to the errors returned by the +.Fn lstat , +the +.Fn fstatat +may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er EINVAL +The value of the +.Fa flag +argument is not valid. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.It Bq Er ENOTCAPABLE +.Fa path +is an absolute path, +or contained a ".." component leading to a +directory outside of the directory hierarchy specified by +.Fa fd , +and the process is in capability mode or the +.Dv AT_RESOLVE_BENEATH +flag was specified. +.El +.Sh SEE ALSO +.Xr access 2 , +.Xr chmod 2 , +.Xr chown 2 , +.Xr fhstat 2 , +.Xr statfs 2 , +.Xr utimes 2 , +.Xr sticky 7 , +.Xr symlink 7 +.Sh STANDARDS +The +.Fn stat +and +.Fn fstat +system calls are expected to conform to +.St -p1003.1-90 . +The +.Fn fstatat +system call follows The Open Group Extended API Set 2 specification. +.Sh HISTORY +The +.Fn stat +and +.Fn fstat +system calls appeared in +.At v1 . +The +.Fn lstat +system call appeared in +.Bx 4.2 . +The +.Fn fstatat +system call appeared in +.Fx 8.0 . +.Sh BUGS +Applying +.Fn fstat +to a socket +returns a zeroed buffer, +except for the blocksize field, +and a unique device and inode number. diff --git a/lib/libsys/statfs.2 b/lib/libsys/statfs.2 new file mode 100644 index 000000000000..ab65def11ebb --- /dev/null +++ b/lib/libsys/statfs.2 @@ -0,0 +1,272 @@ +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd July 20, 2025 +.Dt STATFS 2 +.Os +.Sh NAME +.Nm statfs +.Nd get file system statistics +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.Ft int +.Fn statfs "const char *path" "struct statfs *buf" +.Ft int +.Fn fstatfs "int fd" "struct statfs *buf" +.Sh DESCRIPTION +The +.Fn statfs +system call +returns information about a mounted file system. +The +.Fa path +argument +is the path name of any file within the mounted file system. +The +.Fa buf +argument +is a pointer to a +.Vt statfs +structure defined as follows: +.Bd -literal +typedef struct fsid { int32_t val[2]; } fsid_t; /* file system id type */ + +/* + * filesystem statistics + */ + +#define MFSNAMELEN 16 /* length of type name including null */ +#define MNAMELEN 1024 /* size of on/from name bufs */ +#define STATFS_VERSION 0x20140518 /* current version number */ + +struct statfs { +uint32_t f_version; /* structure version number */ +uint32_t f_type; /* type of filesystem */ +uint64_t f_flags; /* copy of mount exported flags */ +uint64_t f_bsize; /* filesystem fragment size */ +uint64_t f_iosize; /* optimal transfer block size */ +uint64_t f_blocks; /* total data blocks in filesystem */ +uint64_t f_bfree; /* free blocks in filesystem */ +int64_t f_bavail; /* free blocks avail to non-superuser */ +uint64_t f_files; /* total file nodes in filesystem */ +int64_t f_ffree; /* free nodes avail to non-superuser */ +uint64_t f_syncwrites; /* count of sync writes since mount */ +uint64_t f_asyncwrites; /* count of async writes since mount */ +uint64_t f_syncreads; /* count of sync reads since mount */ +uint64_t f_asyncreads; /* count of async reads since mount */ +uint64_t f_spare[10]; /* unused spare */ +uint32_t f_namemax; /* maximum filename length */ +uid_t f_owner; /* user that mounted the filesystem */ +fsid_t f_fsid; /* filesystem id */ +char f_charspare[80]; /* spare string space */ +char f_fstypename[MFSNAMELEN]; /* filesystem type name */ +char f_mntfromname[MNAMELEN]; /* mounted filesystem */ +char f_mntonname[MNAMELEN]; /* directory on which mounted */ +}; +.Ed +.Pp +The flags that may be returned include: +.Bl -tag -width MNT_SYNCHRONOUS +.It Dv MNT_ACLS +Access Control List (ACL) support enabled. +.It Dv MNT_ASYNC +No file system I/O is done synchronously. +.It Dv MNT_AUTOMOUNTED +The filesystem was auto-mounted, see +.Xr autofs 4 . +.It Dv MNT_DEFEXPORTED +The file system is exported for both reading and writing to any Internet host. +.It Dv MNT_GJOURNAL +Journaling with gjournal is enabled (see +.Xr gjournal 8 ) . +.It Dv MNT_EXKERB +The file system is exported with Kerberos uid mapping. +.It Dv MNT_EXPORTANON +The file system maps all remote accesses to the anonymous user. +.It Dv MNT_EXPORTED +The file system is exported for both reading and writing. +.It Dv MNT_EXPUBLIC +The file system is exported publicly (WebNFS). +.It Dv MNT_EXRDONLY +The file system is exported read-only. +.It Dv MNT_IGNORE +The file system should not be listed, e.g. by +.Xr df 1 . +.It Dv MNT_LOCAL +The file system resides locally. +.It Dv MNT_MULTILABEL +Mandatory Access Control (MAC) support for individual objects +(see +.Xr mac 4 ) . +.It Dv MNT_NAMEDATTR +The file system supports named attributes as described in +.Xr named_attribute 7 . +.It Dv MNT_NFS4ACLS +ACLs in NFSv4 variant are supported. +.It Dv MNT_NOATIME +Updating of file access times is disabled. +.It Dv MNT_NOCLUSTERR +Read clustering is disabled. +.It Dv MNT_NOCLUSTERW +Write clustering is disabled. +.It Dv MNT_NOEXEC +Files may not be executed from the file system. +.It Dv MNT_NOSUID +Setuid and setgid bits on files are not honored when they are executed. +.It Dv MNT_NOSYMFOLLOW +Symbolic links are not followed. +.It Dv MNT_SOFTDEP +Soft updates being done (see +.Xr ffs 4 ) . +.It Dv MNT_SUIDDIR +Special handling of SUID bit on directories. +.It Dv MNT_SUJ +Soft-updates with journaling being done. +.It Dv MNT_SYNCHRONOUS +All I/O to the file system is done synchronously. +.It Dv MNT_QUOTA +The file system has quotas enabled on it. +.It Dv MNT_RDONLY +The file system is mounted read-only; +Even the super-user may not write on it. +.It Dv MNT_ROOTFS +Identifies the root file system. +.It Dv MNT_UNION +Union with underlying file system. +.It Dv MNT_UNTRUSTED +The file system was mounted with the +.Cm untrusted +option, which indicates media of unknown provenance or integrity. +Currently honored by +.Xr ffs 4 . +.It Dv MNT_USER +The file system has been mounted by a user. +.It Dv MNT_VERIFIED +The file system is marked as verified, no fingerprint check on +.Xr execve 2 +is needed, see +.Xr mac_veriexec 4 . +.El +.Pp +Fields that are undefined for a particular file system are set to -1. +The +.Fn fstatfs +system call +returns the same information about an open file referenced by descriptor +.Fa fd . +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn statfs +system call +fails if one or more of the following are true: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix of +.Fa path +is not a directory. +.It Bq Er ENAMETOOLONG +The length of a component of +.Fa path +exceeds 255 characters, +or the length of +.Fa path +exceeds 1023 characters. +.It Bq Er ENOENT +The file referred to by +.Fa path +does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix of +.Fa path . +.It Bq Er ELOOP +Too many symbolic links were encountered in translating +.Fa path . +.It Bq Er EFAULT +The +.Fa buf +or +.Fa path +argument +points to an invalid address. +.It Bq Er EIO +An +.Tn I/O +error occurred while reading from or writing to the file system. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.El +.Pp +The +.Fn fstatfs +system call +fails if one or more of the following are true: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument +is not a valid open file descriptor. +.It Bq Er EFAULT +The +.Fa buf +argument +points to an invalid address. +.It Bq Er EIO +An +.Tn I/O +error occurred while reading from or writing to the file system. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.El +.Sh NOTES +The fields in the +.Vt statfs +structure have been defined to provide the parameters relevant for +traditional UNIX file systems. +For some other file systems, values that have similar, but not +identical, semantics to those described above may be returned. +An example is msdosfs, which in case of FAT12 or FAT16 file systems +reports the number of available and of free root directory entries +instead of inodes +.Po +where 1 to 21 such directory entries are required to store +each file or directory name or disk label +.Pc . +.Sh SEE ALSO +.Xr fhstatfs 2 , +.Xr getfsstat 2 , +.Xr named_attribute 7 +.Sh HISTORY +The +.Fn statfs +system call first appeared in +.Bx 4.4 . diff --git a/lib/libsys/swapon.2 b/lib/libsys/swapon.2 new file mode 100644 index 000000000000..23ed0bc2aa83 --- /dev/null +++ b/lib/libsys/swapon.2 @@ -0,0 +1,160 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd December 8, 2021 +.Dt SWAPON 2 +.Os +.Sh NAME +.Nm swapon , swapoff +.Nd control devices for interleaved paging/swapping +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In vm/vm_param.h +.In vm/swap_pager.h +.Pp +.In unistd.h +.Ft int +.Fn swapon "const char *special" +.Ft int +.Fn swapoff "const char *special" "u_int flags" +.Sh DESCRIPTION +The +.Fn swapon +system call +makes the block device +.Fa special +available to the system for +allocation for paging and swapping. +The names of potentially +available devices are known to the system and defined at system +configuration time. +The size of the swap area on +.Fa special +is calculated at the time the device is first made available +for swapping. +.Pp +The +.Fn swapoff +system call disables paging and swapping on the given device. +All associated swap metadata are deallocated, and the device +is made available for other purposes. +.Pp +The +.Fa special +argument points to the name of the device or file used for swapping. +The +.Va flags +argument takes the following flags: +.Bl -tag -width SWAPOFF_FORCE +.It Dv SWAPOFF_FORCE +Overrides a very conservative check that prevents swapoff +if the total amount of free memory and remaining swap +devices space might be unsufficient for the system to continue +operating. +.El +.Sh RETURN VALUES +If an error has occurred, a value of -1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +Both +.Fn swapon +and +.Fn swapoff +can fail if: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named device does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EPERM +The caller is not the super-user. +.It Bq Er EFAULT +The +.Fa special +argument +points outside the process's allocated address space. +.El +.Pp +Additionally, +.Fn swapon +can fail for the following reasons: +.Bl -tag -width Er +.It Bq Er ENOTBLK +The +.Fa special +argument +is not a block device. +.It Bq Er EBUSY +The device specified by +.Fa special +has already +been made available for swapping +.It Bq Er ENXIO +The major device number of +.Fa special +is out of range (this indicates no device driver exists +for the associated hardware). +.It Bq Er EIO +An I/O error occurred while opening the swap device. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system to open the +swap device. +.El +.Pp +Lastly, +.Fn swapoff +can fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The system is not currently swapping to +.Fa special . +.It Bq Er ENOMEM +Not enough virtual memory is available to safely disable +paging and swapping to the given device. +.El +.Sh SEE ALSO +.Xr config 8 , +.Xr swapon 8 , +.Xr sysctl 8 +.Sh HISTORY +The +.Fn swapon +system call appeared in +.Bx 4.0 . +The +.Fn swapoff +system call appeared in +.Fx 5.1 . diff --git a/lib/libsys/symlink.2 b/lib/libsys/symlink.2 new file mode 100644 index 000000000000..b5d878aaae50 --- /dev/null +++ b/lib/libsys/symlink.2 @@ -0,0 +1,207 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd April 15, 2025 +.Dt SYMLINK 2 +.Os +.Sh NAME +.Nm symlink , +.Nm symlinkat +.Nd make symbolic link to a file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn symlink "const char *name1" "const char *name2" +.Ft int +.Fn symlinkat "const char *name1" "int fd" "const char *name2" +.Sh DESCRIPTION +A symbolic link +.Fa name2 +is created to +.Fa name1 +.Fa ( name2 +is the name of the +file created, +.Fa name1 +is the string +used in creating the symbolic link). +Either name may be an arbitrary path name; the files need not +be on the same file system. +.Pp +The +.Fn symlinkat +system call is equivalent to +.Fn symlink +except in the case where +.Fa name2 +specifies a relative path. +In this case the symbolic link is created relative to the directory +associated with the file descriptor +.Fa fd +instead of the current working directory. +If +.Fn symlinkat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is +identical to a call to +.Fn symlink . +.Sh RETURN VALUES +.Rv -std symlink +.Sh ERRORS +The symbolic link succeeds unless: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the +.Fa name2 +path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of the +.Fa name2 +pathname exceeded 255 characters, +or the entire length of either path name exceeded 1023 characters. +.It Bq Er ENOENT +A component of the +.Fa name2 +path prefix does not exist. +.It Bq Er EOPNOTSUPP +The file system containing the file named by +.Fa name2 +does not support symbolic links. +.It Bq Er EACCES +A component of the +.Fa name2 +path prefix denies search permission, or write permission is denied on the +parent directory of the file to be created. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the +.Fa name2 +path name. +.It Bq Er EEXIST +The path name pointed at by the +.Fa name2 +argument +already exists. +.It Bq Er EPERM +The parent directory of the file named by +.Fa name2 +has its immutable flag set, see the +.Xr chflags 2 +manual page for more information. +.It Bq Er EIO +An I/O error occurred while making the directory entry for +.Fa name2 , +allocating the inode for +.Fa name2 , +or writing out the link contents of +.Fa name2 . +.It Bq Er EROFS +The file +.Fa name2 +would reside on a read-only file system. +.It Bq Er ENOSPC +The directory in which the entry for the new symbolic link is being placed +cannot be extended because there is no space left on the file +system containing the directory. +.It Bq Er ENOSPC +The new symbolic link cannot be created because +there is no space left on the file +system that will contain the symbolic link. +.It Bq Er ENOSPC +There are no free inodes on the file system on which the +symbolic link is being created. +.It Bq Er EDQUOT +The directory in which the entry for the new symbolic link +is being placed cannot be extended because the +user's quota of disk blocks on the file system +containing the directory has been exhausted. +.It Bq Er EDQUOT +The new symbolic link cannot be created because the user's +quota of disk blocks on the file system that will +contain the symbolic link has been exhausted. +.It Bq Er EDQUOT +The user's quota of inodes on the file system on +which the symbolic link is being created has been exhausted. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.It Bq Er EFAULT +The +.Fa name1 +or +.Fa name2 +argument +points outside the process's allocated address space. +.El +.Pp +In addition to the errors returned by the +.Fn symlink , +the +.Fn symlinkat +may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa name2 +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er ENOTDIR +The +.Fa name2 +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El +.Sh SEE ALSO +.Xr ln 1 , +.Xr chflags 2 , +.Xr link 2 , +.Xr lstat 2 , +.Xr readlink 2 , +.Xr unlink 2 , +.Xr symlink 7 +.Sh STANDARDS +The +.Fn symlinkat +system call follows The Open Group Extended API Set 2 specification. +.Sh HISTORY +The +.Fn symlink +system call appeared in +.Bx 4.2 . +The +.Fn symlinkat +system call appeared in +.Fx 8.0 . diff --git a/lib/libsys/sync.2 b/lib/libsys/sync.2 new file mode 100644 index 000000000000..d99e4c70e013 --- /dev/null +++ b/lib/libsys/sync.2 @@ -0,0 +1,74 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd December 1, 2017 +.Dt SYNC 2 +.Os +.Sh NAME +.Nm sync +.Nd "schedule file system updates" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft void +.Fn sync void +.Sh DESCRIPTION +The +.Fn sync +system call forces a write of dirty (modified) buffers +in the block buffer cache out +to disk. +The kernel keeps this information in core to reduce +the number of disk I/O transfers required by the system. +As information in the cache is lost after a system crash, a +.Fn sync +system call is issued +frequently +by the kernel process +.Xr syncer 4 +(about every 30 seconds). +.Pp +The +.Xr fsync 2 +system call +may be used to synchronize individual file descriptor +attributes. +.Sh SEE ALSO +.Xr fsync 2 , +.Xr syncer 4 , +.Xr sync 8 +.Sh HISTORY +The +.Fn sync +function appeared in +.At v3 . +.Sh BUGS +The +.Fn sync +system call +may return before the buffers are completely flushed. diff --git a/lib/libsys/sysarch.2 b/lib/libsys/sysarch.2 new file mode 100644 index 000000000000..6144cd44fb37 --- /dev/null +++ b/lib/libsys/sysarch.2 @@ -0,0 +1,78 @@ +.\" $NetBSD: sysarch.2,v 1.6 1998/02/25 21:24:57 perry Exp $ +.\" +.\" Copyright (c) 1980, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd October 11, 1993 +.Dt SYSARCH 2 +.Os +.Sh NAME +.Nm sysarch +.Nd architecture-dependent system call +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In machine/sysarch.h +.Ft int +.Fn sysarch "int number" "void *args" +.Sh DESCRIPTION +The +.Fn sysarch +system call +performs the architecture-dependent function +specified by +.Fa number +with the arguments specified by the +.Fa args +pointer. +The +.Fa args +argument +is a pointer to a structure defining the actual +arguments of the function. +Symbolic constants and argument structures +for the architecture-dependent +functions can be found in the header file +.In machine/sysarch.h . +.Pp +The +.Fn sysarch +system call should never be called directly by +user programs. +Instead, they should access +its functions using the architecture-dependent +library. +.Sh RETURN VALUES +See the manual pages for specific architecture-dependent system calls +for information about their return values. +.Sh SEE ALSO +.Xr i386_get_ioperm 2 , +.Xr i386_get_ldt 2 , +.Xr i386_vm86 2 +.Sh HISTORY +This manual page was taken from +.Nx . diff --git a/lib/libsys/syscall.2 b/lib/libsys/syscall.2 new file mode 100644 index 000000000000..24d25a6ce170 --- /dev/null +++ b/lib/libsys/syscall.2 @@ -0,0 +1,74 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd June 16, 1993 +.Dt SYSCALL 2 +.Os +.Sh NAME +.Nm syscall , +.Nm __syscall +.Nd indirect system call +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/syscall.h +.In unistd.h +.Ft int +.Fn syscall "int number" ... +.Ft off_t +.Fn __syscall "quad_t number" ... +.Sh DESCRIPTION +The +.Fn syscall +function +performs the system call whose assembly language +interface has the specified +.Fa number +with the specified arguments. +Symbolic constants for system calls can be found in the header file +.In sys/syscall.h . +The +.Fn __syscall +form should be used when one or more of the arguments is a +64-bit argument to ensure that argument alignment is correct. +This system call is useful for testing new system calls that +do not have entries in the C library. +.Sh RETURN VALUES +The return values are 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 code is stored in +.Va errno . +.Sh HISTORY +The +.Fn syscall +function appeared in +.Bx 4.0 . +.Sh BUGS +There is no way to simulate system calls that have multiple return values +such as +.Xr pipe 2 . diff --git a/lib/libsys/syscalls.map b/lib/libsys/syscalls.map new file mode 100644 index 000000000000..69fce2ea7c63 --- /dev/null +++ b/lib/libsys/syscalls.map @@ -0,0 +1,816 @@ +/* + * FreeBSD system call symbols. + * + * DO NOT EDIT-- this file is automatically @generated. + */ + +FBSDprivate_1.0 { + _syscall; + __sys_syscall; + __sys_exit; + _fork; + __sys_fork; + _read; + __sys_read; + _write; + __sys_write; + _open; + __sys_open; + _close; + __sys_close; + _wait4; + __sys_wait4; + _link; + __sys_link; + _unlink; + __sys_unlink; + _chdir; + __sys_chdir; + _fchdir; + __sys_fchdir; + _chmod; + __sys_chmod; + _chown; + __sys_chown; + _break; + __sys_break; + _getpid; + __sys_getpid; + _mount; + __sys_mount; + _unmount; + __sys_unmount; + _setuid; + __sys_setuid; + _getuid; + __sys_getuid; + _geteuid; + __sys_geteuid; + _ptrace; + __sys_ptrace; + _recvmsg; + __sys_recvmsg; + _sendmsg; + __sys_sendmsg; + _recvfrom; + __sys_recvfrom; + _accept; + __sys_accept; + _getpeername; + __sys_getpeername; + _getsockname; + __sys_getsockname; + _access; + __sys_access; + _chflags; + __sys_chflags; + _fchflags; + __sys_fchflags; + _sync; + __sys_sync; + _kill; + __sys_kill; + _getppid; + __sys_getppid; + _dup; + __sys_dup; + _getegid; + __sys_getegid; + _profil; + __sys_profil; + _ktrace; + __sys_ktrace; + _getgid; + __sys_getgid; + _getlogin; + __sys_getlogin; + _setlogin; + __sys_setlogin; + _acct; + __sys_acct; + _sigaltstack; + __sys_sigaltstack; + _ioctl; + __sys_ioctl; + _reboot; + __sys_reboot; + _revoke; + __sys_revoke; + _symlink; + __sys_symlink; + _readlink; + __sys_readlink; + _execve; + __sys_execve; + _umask; + __sys_umask; + _chroot; + __sys_chroot; + _msync; + __sys_msync; + __sys_vfork; + _munmap; + __sys_munmap; + _mprotect; + __sys_mprotect; + _madvise; + __sys_madvise; + _mincore; + __sys_mincore; + _getgroups; + __sys_getgroups; + _setgroups; + __sys_setgroups; + _getpgrp; + __sys_getpgrp; + _setpgid; + __sys_setpgid; + _setitimer; + __sys_setitimer; + _swapon; + __sys_swapon; + _getitimer; + __sys_getitimer; + _getdtablesize; + __sys_getdtablesize; + _dup2; + __sys_dup2; + _fcntl; + __sys_fcntl; + _select; + __sys_select; + _fsync; + __sys_fsync; + _setpriority; + __sys_setpriority; + _socket; + __sys_socket; + _connect; + __sys_connect; + _getpriority; + __sys_getpriority; + _bind; + __sys_bind; + _setsockopt; + __sys_setsockopt; + _listen; + __sys_listen; + _gettimeofday; + __sys_gettimeofday; + _getrusage; + __sys_getrusage; + _getsockopt; + __sys_getsockopt; + _readv; + __sys_readv; + _writev; + __sys_writev; + _settimeofday; + __sys_settimeofday; + _fchown; + __sys_fchown; + _fchmod; + __sys_fchmod; + _setreuid; + __sys_setreuid; + _setregid; + __sys_setregid; + _rename; + __sys_rename; + _flock; + __sys_flock; + _mkfifo; + __sys_mkfifo; + _sendto; + __sys_sendto; + _shutdown; + __sys_shutdown; + _socketpair; + __sys_socketpair; + _mkdir; + __sys_mkdir; + _rmdir; + __sys_rmdir; + _utimes; + __sys_utimes; + _adjtime; + __sys_adjtime; + _setsid; + __sys_setsid; + _quotactl; + __sys_quotactl; + _nlm_syscall; + __sys_nlm_syscall; + _nfssvc; + __sys_nfssvc; + _lgetfh; + __sys_lgetfh; + _getfh; + __sys_getfh; + _sysarch; + __sys_sysarch; + _rtprio; + __sys_rtprio; + _semsys; + __sys_semsys; + _msgsys; + __sys_msgsys; + _shmsys; + __sys_shmsys; + _setfib; + __sys_setfib; + _ntp_adjtime; + __sys_ntp_adjtime; + _setgid; + __sys_setgid; + _setegid; + __sys_setegid; + _seteuid; + __sys_seteuid; + _pathconf; + __sys_pathconf; + _fpathconf; + __sys_fpathconf; + _getrlimit; + __sys_getrlimit; + _setrlimit; + __sys_setrlimit; + ___syscall; + __sys___syscall; + ___sysctl; + __sys___sysctl; + _mlock; + __sys_mlock; + _munlock; + __sys_munlock; + _undelete; + __sys_undelete; + _futimes; + __sys_futimes; + _getpgid; + __sys_getpgid; + _poll; + __sys_poll; + _semget; + __sys_semget; + _semop; + __sys_semop; + _msgget; + __sys_msgget; + _msgsnd; + __sys_msgsnd; + _msgrcv; + __sys_msgrcv; + _shmat; + __sys_shmat; + _shmdt; + __sys_shmdt; + _shmget; + __sys_shmget; + _clock_gettime; + __sys_clock_gettime; + _clock_settime; + __sys_clock_settime; + _clock_getres; + __sys_clock_getres; + _ktimer_create; + __sys_ktimer_create; + _ktimer_delete; + __sys_ktimer_delete; + _ktimer_settime; + __sys_ktimer_settime; + _ktimer_gettime; + __sys_ktimer_gettime; + _ktimer_getoverrun; + __sys_ktimer_getoverrun; + _nanosleep; + __sys_nanosleep; + _ffclock_getcounter; + __sys_ffclock_getcounter; + _ffclock_setestimate; + __sys_ffclock_setestimate; + _ffclock_getestimate; + __sys_ffclock_getestimate; + _clock_nanosleep; + __sys_clock_nanosleep; + _clock_getcpuclockid2; + __sys_clock_getcpuclockid2; + _ntp_gettime; + __sys_ntp_gettime; + _minherit; + __sys_minherit; + _rfork; + __sys_rfork; + _issetugid; + __sys_issetugid; + _lchown; + __sys_lchown; + _aio_read; + __sys_aio_read; + _aio_write; + __sys_aio_write; + _lio_listio; + __sys_lio_listio; + _lchmod; + __sys_lchmod; + _lutimes; + __sys_lutimes; + _preadv; + __sys_preadv; + _pwritev; + __sys_pwritev; + _fhopen; + __sys_fhopen; + _modnext; + __sys_modnext; + _modstat; + __sys_modstat; + _modfnext; + __sys_modfnext; + _modfind; + __sys_modfind; + _kldload; + __sys_kldload; + _kldunload; + __sys_kldunload; + _kldfind; + __sys_kldfind; + _kldnext; + __sys_kldnext; + _kldstat; + __sys_kldstat; + _kldfirstmod; + __sys_kldfirstmod; + _getsid; + __sys_getsid; + _setresuid; + __sys_setresuid; + _setresgid; + __sys_setresgid; + _aio_return; + __sys_aio_return; + _aio_suspend; + __sys_aio_suspend; + _aio_cancel; + __sys_aio_cancel; + _aio_error; + __sys_aio_error; + _mlockall; + __sys_mlockall; + _munlockall; + __sys_munlockall; + ___getcwd; + __sys___getcwd; + _sched_setparam; + __sys_sched_setparam; + _sched_getparam; + __sys_sched_getparam; + _sched_setscheduler; + __sys_sched_setscheduler; + _sched_getscheduler; + __sys_sched_getscheduler; + _sched_yield; + __sys_sched_yield; + _sched_get_priority_max; + __sys_sched_get_priority_max; + _sched_get_priority_min; + __sys_sched_get_priority_min; + _sched_rr_get_interval; + __sys_sched_rr_get_interval; + _utrace; + __sys_utrace; + _kldsym; + __sys_kldsym; + _jail; + __sys_jail; + _nnpfs_syscall; + __sys_nnpfs_syscall; + _sigprocmask; + __sys_sigprocmask; + _sigsuspend; + __sys_sigsuspend; + _sigpending; + __sys_sigpending; + _sigtimedwait; + __sys_sigtimedwait; + _sigwaitinfo; + __sys_sigwaitinfo; + ___acl_get_file; + __sys___acl_get_file; + ___acl_set_file; + __sys___acl_set_file; + ___acl_get_fd; + __sys___acl_get_fd; + ___acl_set_fd; + __sys___acl_set_fd; + ___acl_delete_file; + __sys___acl_delete_file; + ___acl_delete_fd; + __sys___acl_delete_fd; + ___acl_aclcheck_file; + __sys___acl_aclcheck_file; + ___acl_aclcheck_fd; + __sys___acl_aclcheck_fd; + _extattrctl; + __sys_extattrctl; + _extattr_set_file; + __sys_extattr_set_file; + _extattr_get_file; + __sys_extattr_get_file; + _extattr_delete_file; + __sys_extattr_delete_file; + _aio_waitcomplete; + __sys_aio_waitcomplete; + _getresuid; + __sys_getresuid; + _getresgid; + __sys_getresgid; + _kqueue; + __sys_kqueue; + _extattr_set_fd; + __sys_extattr_set_fd; + _extattr_get_fd; + __sys_extattr_get_fd; + _extattr_delete_fd; + __sys_extattr_delete_fd; + ___setugid; + __sys___setugid; + _eaccess; + __sys_eaccess; + _afs3_syscall; + __sys_afs3_syscall; + _nmount; + __sys_nmount; + ___mac_get_proc; + __sys___mac_get_proc; + ___mac_set_proc; + __sys___mac_set_proc; + ___mac_get_fd; + __sys___mac_get_fd; + ___mac_get_file; + __sys___mac_get_file; + ___mac_set_fd; + __sys___mac_set_fd; + ___mac_set_file; + __sys___mac_set_file; + _kenv; + __sys_kenv; + _lchflags; + __sys_lchflags; + _uuidgen; + __sys_uuidgen; + _sendfile; + __sys_sendfile; + _mac_syscall; + __sys_mac_syscall; + _ksem_close; + __sys_ksem_close; + _ksem_post; + __sys_ksem_post; + _ksem_wait; + __sys_ksem_wait; + _ksem_trywait; + __sys_ksem_trywait; + _ksem_init; + __sys_ksem_init; + _ksem_open; + __sys_ksem_open; + _ksem_unlink; + __sys_ksem_unlink; + _ksem_getvalue; + __sys_ksem_getvalue; + _ksem_destroy; + __sys_ksem_destroy; + ___mac_get_pid; + __sys___mac_get_pid; + ___mac_get_link; + __sys___mac_get_link; + ___mac_set_link; + __sys___mac_set_link; + _extattr_set_link; + __sys_extattr_set_link; + _extattr_get_link; + __sys_extattr_get_link; + _extattr_delete_link; + __sys_extattr_delete_link; + ___mac_execve; + __sys___mac_execve; + _sigaction; + __sys_sigaction; + _sigreturn; + __sys_sigreturn; + _getcontext; + __sys_getcontext; + _setcontext; + __sys_setcontext; + _swapcontext; + __sys_swapcontext; + ___acl_get_link; + __sys___acl_get_link; + ___acl_set_link; + __sys___acl_set_link; + ___acl_delete_link; + __sys___acl_delete_link; + ___acl_aclcheck_link; + __sys___acl_aclcheck_link; + _sigwait; + __sys_sigwait; + _thr_create; + __sys_thr_create; + _thr_exit; + __sys_thr_exit; + _thr_self; + __sys_thr_self; + _thr_kill; + __sys_thr_kill; + _jail_attach; + __sys_jail_attach; + _extattr_list_fd; + __sys_extattr_list_fd; + _extattr_list_file; + __sys_extattr_list_file; + _extattr_list_link; + __sys_extattr_list_link; + _ksem_timedwait; + __sys_ksem_timedwait; + _thr_suspend; + __sys_thr_suspend; + _thr_wake; + __sys_thr_wake; + _kldunloadf; + __sys_kldunloadf; + _audit; + __sys_audit; + _auditon; + __sys_auditon; + _getauid; + __sys_getauid; + _setauid; + __sys_setauid; + _getaudit; + __sys_getaudit; + _setaudit; + __sys_setaudit; + _getaudit_addr; + __sys_getaudit_addr; + _setaudit_addr; + __sys_setaudit_addr; + _auditctl; + __sys_auditctl; + __umtx_op; + __sys__umtx_op; + _thr_new; + __sys_thr_new; + _sigqueue; + __sys_sigqueue; + _kmq_open; + __sys_kmq_open; + _kmq_setattr; + __sys_kmq_setattr; + _kmq_timedreceive; + __sys_kmq_timedreceive; + _kmq_timedsend; + __sys_kmq_timedsend; + _kmq_notify; + __sys_kmq_notify; + _kmq_unlink; + __sys_kmq_unlink; + _abort2; + __sys_abort2; + _thr_set_name; + __sys_thr_set_name; + _aio_fsync; + __sys_aio_fsync; + _rtprio_thread; + __sys_rtprio_thread; + _sctp_peeloff; + __sys_sctp_peeloff; + _sctp_generic_sendmsg; + __sys_sctp_generic_sendmsg; + _sctp_generic_sendmsg_iov; + __sys_sctp_generic_sendmsg_iov; + _sctp_generic_recvmsg; + __sys_sctp_generic_recvmsg; + _pread; + __sys_pread; + _pwrite; + __sys_pwrite; + _mmap; + __sys_mmap; + _lseek; + __sys_lseek; + _truncate; + __sys_truncate; + _ftruncate; + __sys_ftruncate; + _thr_kill2; + __sys_thr_kill2; + _shm_unlink; + __sys_shm_unlink; + _cpuset; + __sys_cpuset; + _cpuset_setid; + __sys_cpuset_setid; + _cpuset_getid; + __sys_cpuset_getid; + _cpuset_getaffinity; + __sys_cpuset_getaffinity; + _cpuset_setaffinity; + __sys_cpuset_setaffinity; + _faccessat; + __sys_faccessat; + _fchmodat; + __sys_fchmodat; + _fchownat; + __sys_fchownat; + _fexecve; + __sys_fexecve; + _futimesat; + __sys_futimesat; + _linkat; + __sys_linkat; + _mkdirat; + __sys_mkdirat; + _mkfifoat; + __sys_mkfifoat; + _openat; + __sys_openat; + _readlinkat; + __sys_readlinkat; + _renameat; + __sys_renameat; + _symlinkat; + __sys_symlinkat; + _unlinkat; + __sys_unlinkat; + _posix_openpt; + __sys_posix_openpt; + _jail_get; + __sys_jail_get; + _jail_set; + __sys_jail_set; + _jail_remove; + __sys_jail_remove; + ___semctl; + __sys___semctl; + _msgctl; + __sys_msgctl; + _shmctl; + __sys_shmctl; + _lpathconf; + __sys_lpathconf; + ___cap_rights_get; + __sys___cap_rights_get; + _cap_enter; + __sys_cap_enter; + _cap_getmode; + __sys_cap_getmode; + _pdfork; + __sys_pdfork; + _pdkill; + __sys_pdkill; + _pdgetpid; + __sys_pdgetpid; + _pselect; + __sys_pselect; + _getloginclass; + __sys_getloginclass; + _setloginclass; + __sys_setloginclass; + _rctl_get_racct; + __sys_rctl_get_racct; + _rctl_get_rules; + __sys_rctl_get_rules; + _rctl_get_limits; + __sys_rctl_get_limits; + _rctl_add_rule; + __sys_rctl_add_rule; + _rctl_remove_rule; + __sys_rctl_remove_rule; + _posix_fallocate; + __sys_posix_fallocate; + _posix_fadvise; + __sys_posix_fadvise; + _wait6; + __sys_wait6; + _cap_rights_limit; + __sys_cap_rights_limit; + _cap_ioctls_limit; + __sys_cap_ioctls_limit; + _cap_ioctls_get; + __sys_cap_ioctls_get; + _cap_fcntls_limit; + __sys_cap_fcntls_limit; + _cap_fcntls_get; + __sys_cap_fcntls_get; + _bindat; + __sys_bindat; + _connectat; + __sys_connectat; + _chflagsat; + __sys_chflagsat; + _accept4; + __sys_accept4; + _pipe2; + __sys_pipe2; + _aio_mlock; + __sys_aio_mlock; + _procctl; + __sys_procctl; + _ppoll; + __sys_ppoll; + _futimens; + __sys_futimens; + _utimensat; + __sys_utimensat; + _fdatasync; + __sys_fdatasync; + _fstat; + __sys_fstat; + _fstatat; + __sys_fstatat; + _fhstat; + __sys_fhstat; + _getdirentries; + __sys_getdirentries; + _statfs; + __sys_statfs; + _fstatfs; + __sys_fstatfs; + _getfsstat; + __sys_getfsstat; + _fhstatfs; + __sys_fhstatfs; + _mknodat; + __sys_mknodat; + _kevent; + __sys_kevent; + _cpuset_getdomain; + __sys_cpuset_getdomain; + _cpuset_setdomain; + __sys_cpuset_setdomain; + _getrandom; + __sys_getrandom; + _getfhat; + __sys_getfhat; + _fhlink; + __sys_fhlink; + _fhlinkat; + __sys_fhlinkat; + _fhreadlink; + __sys_fhreadlink; + _funlinkat; + __sys_funlinkat; + _copy_file_range; + __sys_copy_file_range; + ___sysctlbyname; + __sys___sysctlbyname; + _shm_open2; + __sys_shm_open2; + _shm_rename; + __sys_shm_rename; + _sigfastblock; + __sys_sigfastblock; + ___realpathat; + __sys___realpathat; + _close_range; + __sys_close_range; + _rpctls_syscall; + __sys_rpctls_syscall; + ___specialfd; + __sys___specialfd; + _aio_writev; + __sys_aio_writev; + _aio_readv; + __sys_aio_readv; + _fspacectl; + __sys_fspacectl; + _sched_getcpu; + __sys_sched_getcpu; + _swapoff; + __sys_swapoff; + _kqueuex; + __sys_kqueuex; + _membarrier; + __sys_membarrier; + _timerfd_create; + __sys_timerfd_create; + _timerfd_gettime; + __sys_timerfd_gettime; + _timerfd_settime; + __sys_timerfd_settime; + _kcmp; + __sys_kcmp; + _getrlimitusage; + __sys_getrlimitusage; + _fchroot; + __sys_fchroot; + _setcred; + __sys_setcred; + _exterrctl; + __sys_exterrctl; + _inotify_add_watch_at; + __sys_inotify_add_watch_at; + _inotify_rm_watch; + __sys_inotify_rm_watch; +}; diff --git a/lib/libsys/thr_exit.2 b/lib/libsys/thr_exit.2 new file mode 100644 index 000000000000..98c6dd63f7ec --- /dev/null +++ b/lib/libsys/thr_exit.2 @@ -0,0 +1,92 @@ +.\" Copyright (c) 2016 The FreeBSD Foundation +.\" +.\" This documentation was written by +.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" 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 AUTHORS 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 AUTHORS 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. +.\" +.Dd May 5, 2020 +.Dt THR_EXIT 2 +.Os +.Sh NAME +.Nm thr_exit +.Nd terminate current thread +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/thr.h +.Ft void +.Fn thr_exit "long *state" +.Sh DESCRIPTION +.Bf -symbolic +This function is intended for implementing threading. +Normal applications should call +.Xr pthread_exit 3 +instead. +.Ef +.Pp +The +.Fn thr_exit +system call terminates the current kernel-scheduled thread. +.Pp +If the +.Fa state +argument is not +.Dv NULL , +the location pointed to by the argument is +updated with an arbitrary non-zero value, and an +.Xr _umtx_op 2 +.Dv UMTX_OP_WAKE +operation is consequently performed on the location. +.Pp +Attempts to terminate the last thread in the process are silently ignored. +Use +.Xr _exit 2 +syscall to terminate the process. +.Sh RETURN VALUES +The function does not return a value. +A return from the function indicates that the calling thread was the +last one in the process. +.Sh SEE ALSO +.Xr _exit 2 , +.Xr _umtx_op 2 , +.Xr thr_kill 2 , +.Xr thr_kill2 2 , +.Xr thr_new 2 , +.Xr thr_self 2 , +.Xr thr_set_name 2 , +.Xr pthread_exit 3 +.Sh STANDARDS +The +.Fn thr_exit +system call is non-standard and is used by +.Lb libthr +to implement +.St -p1003.1-2001 +.Xr pthread 3 +functionality. +.Sh HISTORY +The +.Fn thr_exit +system call first appeared in +.Fx 5.2 . diff --git a/lib/libsys/thr_kill.2 b/lib/libsys/thr_kill.2 new file mode 100644 index 000000000000..3f3cb0af2a00 --- /dev/null +++ b/lib/libsys/thr_kill.2 @@ -0,0 +1,137 @@ +.\" Copyright (c) 2016 The FreeBSD Foundation +.\" +.\" This documentation was written by +.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" 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 AUTHORS 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 AUTHORS 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. +.\" +.Dd May 5, 2020 +.Dt THR_KILL 2 +.Os +.Sh NAME +.Nm thr_kill +.Nd send signal to thread +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/thr.h +.Ft int +.Fn thr_kill "long id" "int sig" +.Ft int +.Fn thr_kill2 "pid_t pid" "long id" "int sig" +.Sh DESCRIPTION +The +.Fn thr_kill +and +.Fn thr_kill2 +system calls allow sending a signal, specified by the +.Fa sig +argument, to some threads in a process. +For the +.Fn thr_kill +function, signalled threads are always limited to the current process. +For the +.Fn thr_kill2 +function, the +.Fa pid +argument specifies the process with threads to be signalled. +.Pp +The +.Fa id +argument specifies which threads get the signal. +If +.Fa id +is equal to \-1, all threads in the specified process are signalled. +Otherwise, only the thread with the thread identifier equal to the +argument is signalled. +.Pp +The +.Fa sig +argument defines the delivered signal. +It must be a valid signal number or zero. +In the latter case no signal is actually sent, and the call is used to +verify the liveness of the thread. +.Pp +The signal is delivered with +.Dv siginfo +.Dv si_code +set to +.Dv SI_LWP . +.Sh RETURN VALUES +If successful, +.Fn thr_kill +and +.Fn thr_kill2 +will return zero, otherwise \-1 is returned, and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn thr_kill +and +.Fn thr_kill2 +operations return the following errors: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa sig +argument is not zero and does not specify valid signal. +.It Bq Er ESRCH +The specified process or thread was not found. +.El +.Pp +Additionally, the +.Fn thr_kill2 +may return the following errors: +.Bl -tag -width Er +.It Bq Er EPERM +The current process does not have sufficient privilege to check existence or +send a signal to the specified process. +.El +.Sh SEE ALSO +.Xr _umtx_op 2 , +.Xr kill 2 , +.Xr thr_exit 2 , +.Xr thr_new 2 , +.Xr thr_self 2 , +.Xr thr_set_name 2 , +.Xr pthread_kill 3 , +.Xr signal 3 +.Sh STANDARDS +The +.Fn thr_kill +and +.Fn thr_kill2 +system calls are non-standard and are used by the +.Lb libthr +to implement +.St -p1003.1-2001 +.Xr pthread 3 +functionality. +.Sh HISTORY +The +.Fn thr_kill +and +.Fn thr_kill2 +system calls first appeared in +.Fx 5.2 . diff --git a/lib/libsys/thr_new.2 b/lib/libsys/thr_new.2 new file mode 100644 index 000000000000..a04327723c34 --- /dev/null +++ b/lib/libsys/thr_new.2 @@ -0,0 +1,256 @@ +.\" Copyright (c) 2016 The FreeBSD Foundation +.\" +.\" This documentation was written by +.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" 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 AUTHORS 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 AUTHORS 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. +.\" +.Dd May 5, 2020 +.Dt THR_NEW 2 +.Os +.Sh NAME +.Nm thr_new +.Nd create new thread of execution +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/thr.h +.Ft int +.Fn thr_new "struct thr_param *param" "int param_size" +.Sh DESCRIPTION +.Bf -symbolic +This function is intended for implementing threading. +Normal applications should call +.Xr pthread_create 3 +instead. +.Ef +.Pp +The +.Fn thr_new +system call creates a new kernel-scheduled thread of execution in the context +of the current process. +The newly created thread shares all attributes of the process with the +existing kernel-scheduled threads in the process, but has private processor +execution state. +The machine context for the new thread is copied from the creating thread's +context, including coprocessor state. +FPU state and specific machine registers are excluded from the copy. +These are set according to ABI requirements and syscall parameters. +The FPU state for the new thread is reinitialized to clean. +.Pp +The +.Fa param +structure supplies parameters affecting the thread creation. +The structure is defined in the +.In sys/thr.h +header as follows +.Bd -literal +struct thr_param { + void (*start_func)(void *); + void *arg; + char *stack_base; + size_t stack_size; + char *tls_base; + size_t tls_size; + long *child_tid; + long *parent_tid; + int flags; + struct rtprio *rtp; +}; +.Ed +and contains the following fields: +.Bl -tag -width ".Va parent_tid" +.It Va start_func +Pointer to the thread entry function. +The kernel arranges for the new thread to start executing the function +upon the first return to userspace. +.It Va arg +Opaque argument supplied to the entry function. +.It Va stack_base +Stack base address. +The stack must be allocated by the caller. +On some architectures, the ABI might require that the system put information +on the stack to ensure the execution environment for +.Va start_func . +.It Va stack_size +Stack size. +.It Va tls_base +TLS base address. +The value of TLS base is loaded into the ABI-defined machine register +in the new thread context. +.It Va tls_size +TLS size. +.It Va child_tid +Address to store the new thread identifier, for the child's use. +.It Va parent_tid +Address to store the new thread identifier, for the parent's use. +.Pp +Both +.Va child_tid +and +.Va parent_tid +are provided, with the intent that +.Va child_tid +is used by the new thread to get its thread identifier without +issuing the +.Xr thr_self 2 +syscall, while +.Va parent_tid +is used by the thread creator. +The latter is separate from +.Va child_tid +because the new thread might exit and free its thread data before the parent +has a chance to execute far enough to access it. +.It Va flags +Thread creation flags. +The +.Va flags +member may specify the following flags: +.Bl -tag -width ".Dv THR_SYSTEM_SCOPE" +.It Dv THR_SUSPENDED +Create the new thread in the suspended state. +The flag is not currently implemented. +.It Dv THR_SYSTEM_SCOPE +Create the system scope thread. +The flag is not currently implemented. +.It Dv THR_C_RUNTIME +Indicate that the new thread is created by the C language runtime. +It has architecture-specific meaning. +.Pp +On amd64, the flag requests that the specified +.Fa tls_base +was loaded into the +.Va %fsbase +register before calling a signal handler. +.El +.It Va rtp +Real-time scheduling priority for the new thread. +May be +.Dv NULL +to inherit the priority from the +creating thread. +.El +.Pp +The +.Fa param_size +argument should be set to the size of the +.Fa param +structure. +.Pp +After the first successful creation of an additional thread, +the process is marked by the kernel as multi-threaded. +In particular, the +.Dv P_HADTHREADS +flag is set in the process' +.Dv p_flag +(visible in the +.Xr ps 1 +output), and several operations are executed in multi-threaded mode. +For instance, the +.Xr execve 2 +system call terminates all threads but the calling one on successful +execution. +.Sh RETURN VALUES +If successful, +.Fn thr_new +will return zero, otherwise \-1 is returned, and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn thr_new +operation returns the following errors: +.Bl -tag -width Er +.\" When changing this list, consider updating share/man/man3/pthread_create.3, +.\" since that function can return any of these errors. +.It Bq Er EFAULT +The memory pointed to by the +.Fa param +argument is not valid. +.It Bq Er EFAULT +The memory pointed to by the +.Fa param +structure +.Fa child_tid , parent_tid +or +.Fa rtp +arguments is not valid. +.It Bq Er EFAULT +The specified stack base is invalid, or the kernel was unable to put required +initial data on the stack. +.It Bq Er EINVAL +The +.Fa param_size +argument specifies a negative value, or the value is greater than the +largest +.Fa struct param +size the kernel can interpret. +.It Bq Er EINVAL +The +.Fa rtp +member is not +.Dv NULL +and specifies invalid scheduling parameters. +.It Bq Er EINVAL +The specified TLS base is invalid. +.It Bq Er EPERM +The caller does not have permission to set the scheduling parameters or +scheduling policy. +.It Bq Er EPROCLIM +Creation of the new thread would exceed the +.Dv RACCT_NTHR +limit, see +.Xr rctl_get_racct 2 . +.It Bq Er EPROCLIM +Creation of the new thread would exceed the +.Dv kern.threads.max_threads_per_proc +.Xr sysctl 3 +limit. +.It Bq Er ENOMEM +There was not enough kernel memory to allocate the new thread structures. +.El +.Sh SEE ALSO +.Xr ps 1 , +.Xr _umtx_op 2 , +.Xr execve 2 , +.Xr rctl_get_racct 2 , +.Xr thr_exit 2 , +.Xr thr_kill 2 , +.Xr thr_kill2 2 , +.Xr thr_self 2 , +.Xr thr_set_name 2 , +.Xr pthread_create 3 +.Sh STANDARDS +The +.Fn thr_new +system call is non-standard and is used by the +.Lb libthr +to implement +.St -p1003.1-2001 +.Xr pthread 3 +functionality. +.Sh HISTORY +The +.Fn thr_new +system call first appeared in +.Fx 5.2 . diff --git a/lib/libsys/thr_self.2 b/lib/libsys/thr_self.2 new file mode 100644 index 000000000000..42d146448c05 --- /dev/null +++ b/lib/libsys/thr_self.2 @@ -0,0 +1,92 @@ +.\" Copyright (c) 2016 The FreeBSD Foundation +.\" +.\" This documentation was written by +.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" 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 AUTHORS 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 AUTHORS 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. +.\" +.Dd May 5, 2020 +.Dt THR_SELF 2 +.Os +.Sh NAME +.Nm thr_self +.Nd return thread identifier for the calling thread +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/thr.h +.Ft int +.Fn thr_self "long *id" +.Sh DESCRIPTION +The +.Fn thr_self +system call stores the system-wide thread identifier for the current +kernel-scheduled thread in the variable pointed by the argument +.Va id . +.Pp +The thread identifier is an integer in the range from +.Dv PID_MAX + 2 +(100001) to +.Dv INT_MAX . +The thread identifier is guaranteed to be unique at any given time, +for each running thread in the system. +After the thread exits, the identifier may be reused. +.Sh RETURN VALUES +If successful, +.Fn thr_self +will return zero, otherwise \-1 is returned, and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn thr_self +operation may return the following errors: +.Bl -tag -width Er +.It Bq Er EFAULT +The memory pointed to by the +.Fa id +argument is not valid. +.El +.Sh SEE ALSO +.Xr _umtx_op 2 , +.Xr thr_exit 2 , +.Xr thr_kill 2 , +.Xr thr_kill2 2 , +.Xr thr_new 2 , +.Xr thr_set_name 2 , +.Xr pthread_getthreadid_np 3 , +.Xr pthread_self 3 +.Sh STANDARDS +The +.Fn thr_self +system call is non-standard and is used by +.Lb libthr +to implement +.St -p1003.1-2001 +.Xr pthread 3 +functionality. +.Sh HISTORY +The +.Fn thr_self +system call first appeared in +.Fx 5.2 . diff --git a/lib/libsys/thr_set_name.2 b/lib/libsys/thr_set_name.2 new file mode 100644 index 000000000000..38205f7f30b8 --- /dev/null +++ b/lib/libsys/thr_set_name.2 @@ -0,0 +1,96 @@ +.\" Copyright (c) 2016 The FreeBSD Foundation +.\" +.\" This documentation was written by +.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" 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 AUTHORS 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 AUTHORS 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. +.\" +.Dd May 5, 2020 +.Dt THR_SET_NAME 2 +.Os +.Sh NAME +.Nm thr_set_name +.Nd set user-visible thread name +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/thr.h +.Ft int +.Fn thr_set_name "long id" "const char *name" +.Sh DESCRIPTION +The +.Fn thr_set_name +system call sets the user-visible name for the thread with the identifier +.Va id +in the current process to the NUL-terminated string +.Va name . +The name will be silently truncated to fit into a buffer of +.Dv MAXCOMLEN + 1 +bytes. +The thread name can be seen in the output of the +.Xr ps 1 +and +.Xr top 1 +commands, in the kernel debuggers and kernel tracing facility outputs, +and in userland debuggers and program core files, as notes. +.Sh RETURN VALUES +If successful, +.Fn thr_set_name +returns zero; otherwise, \-1 is returned, and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn thr_set_name +system call may return the following errors: +.Bl -tag -width Er +.It Bq Er EFAULT +The memory pointed to by the +.Fa name +argument is not valid. +.It Bq Er ESRCH +The thread with the identifier +.Fa id +does not exist in the current process. +.El +.Sh SEE ALSO +.Xr ps 1 , +.Xr _umtx_op 2 , +.Xr thr_exit 2 , +.Xr thr_kill 2 , +.Xr thr_kill2 2 , +.Xr thr_new 2 , +.Xr thr_self 2 , +.Xr pthread_set_name_np 3 , +.Xr ddb 4 , +.Xr ktr 9 +.Sh STANDARDS +The +.Fn thr_set_name +system call is non-standard and is used by the +.Lb libthr . +.Sh HISTORY +The +.Fn thr_set_name +system call first appeared in +.Fx 5.2 . diff --git a/lib/libsys/thr_suspend.2 b/lib/libsys/thr_suspend.2 new file mode 100644 index 000000000000..74eacb0daa3c --- /dev/null +++ b/lib/libsys/thr_suspend.2 @@ -0,0 +1,131 @@ +.\" Copyright (c) 2016 The FreeBSD Foundation +.\" +.\" This documentation was written by +.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" 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 AUTHORS 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 AUTHORS 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. +.\" +.Dd May 5, 2020 +.Dt THR_SUSPEND 2 +.Os +.Sh NAME +.Nm thr_suspend +.Nd suspend the calling thread +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/thr.h +.Ft int +.Fn thr_suspend "struct timespec *timeout" +.Sh DESCRIPTION +.Bf -symbolic +This function is intended for implementing threading. +Normal applications should use +.Xr pthread_cond_timedwait 3 +together with +.Xr pthread_cond_broadcast 3 +for typical safe suspension with cooperation of the thread +being suspended, or +.Xr pthread_suspend_np 3 +and +.Xr pthread_resume_np 3 +in some specific situations, instead. +.Ef +.Pp +The +.Fn thr_suspend +system call puts the calling thread in a suspended state, where it is +not eligible for CPU time. +This state is exited by another thread calling +.Xr thr_wake 2 , +when the time interval specified by +.Fa timeout +has elapsed, +or by the delivery of a signal to the suspended thread. +.Pp +If the +.Fa timeout +argument is +.Dv NULL , +the suspended state can be only terminated by explicit +.Fn thr_wake +or signal. +.Pp +If a wake from +.Xr thr_wake 2 +was delivered before the +.Nm +call, the thread is not put into a suspended state. +Instead, the call +returns immediately without an error. +.Pp +If a thread previously called +.Xr thr_wake 2 +with its own thread identifier, which resulted in setting the internal kernel +flag to immediately abort interruptible sleeps with an +.Er EINTR +error +.Po +see +.Xr thr_wake 2 +.Pc , +the flag is cleared. +As with +.Xr thr_wake 2 +called from another thread, the next +.Nm +call does not result in suspension. +.Sh RETURN VALUES +.Rv -std thr_suspend +.Sh ERRORS +The +.Fn thr_suspend +operation returns the following errors: +.Bl -tag -width Er +.It Bq Er EFAULT +The memory pointed to by the +.Fa timeout +argument is not valid. +.It Bq Er ETIMEDOUT +The specified timeout expired. +.It Bq Er ETIMEDOUT +The +.Fa timeout +argument specified a zero time interval. +.It Bq Er EINTR +The sleep was interrupted by a signal. +.El +.Sh SEE ALSO +.Xr ps 1 , +.Xr thr_wake 2 , +.Xr pthread_resume_np 3 , +.Xr pthread_suspend_np 3 +.Sh STANDARDS +The +.Fn thr_suspend +system call is non-standard. +.Sh HISTORY +The +.Fn thr_suspend +system call first appeared in +.Fx 5.2 . diff --git a/lib/libsys/thr_wake.2 b/lib/libsys/thr_wake.2 new file mode 100644 index 000000000000..9091a2b0c06e --- /dev/null +++ b/lib/libsys/thr_wake.2 @@ -0,0 +1,114 @@ +.\" Copyright (c) 2016 The FreeBSD Foundation +.\" +.\" This documentation was written by +.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" 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 AUTHORS 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 AUTHORS 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. +.\" +.Dd May 5, 2020 +.Dt THR_WAKE 2 +.Os +.Sh NAME +.Nm thr_wake +.Nd wake up the suspended thread +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/thr.h +.Ft int +.Fn thr_wake "long id" +.Sh DESCRIPTION +.Bf -symbolic +This function is intended for implementing threading. +Normal applications should use +.Xr pthread_cond_timedwait 3 +together with +.Xr pthread_cond_broadcast 3 +for typical safe suspension with cooperation of the thread +being suspended, or +.Xr pthread_suspend_np 3 +and +.Xr pthread_resume_np 3 +in some specific situations, instead. +.Ef +.Pp +Passing the thread identifier of the calling thread +.Po +see +.Xr thr_self 2 +.Pc +to +.Fn thr_wake +sets a thread's flag to cause the next signal-interruptible sleep +of that thread in the kernel to fail immediately with the +.Er EINTR +error. +The flag is cleared by an interruptible sleep attempt or by a call to +.Xr thr_suspend 2 . +This is used by the system threading library to implement cancellation. +.Pp +If +.Fa id +is not equal to the current thread identifier, the specified thread is +woken up if suspended by the +.Xr thr_suspend 2 +system call. +If the thread is not suspended at the time of the +.Nm +call, the wake is remembered and the next attempt of the thread to +suspend itself with the +.Xr thr_suspend 2 +results in immediate return with success. +Only one wake is remembered. +.Sh RETURN VALUES +.Rv -std thr_wake +.Sh ERRORS +The +.Fn thr_wake +operation returns these errors: +.Bl -tag -width Er +.It Bq Er ESRCH +The specified thread was not found or does not belong to the process +of the calling thread. +.El +.Sh SEE ALSO +.Xr ps 1 , +.Xr thr_self 2 , +.Xr thr_suspend 2 , +.Xr pthread_cancel 3 , +.Xr pthread_resume_np 3 , +.Xr pthread_suspend_np 3 +.Sh STANDARDS +The +.Fn thr_suspend +system call is non-standard and is used by +.Lb libthr +to implement +.St -p1003.1-2001 +.Xr pthread 3 +functionality. +.Sh HISTORY +The +.Fn thr_suspend +system call first appeared in +.Fx 5.2 . diff --git a/lib/libsys/timer_create.2 b/lib/libsys/timer_create.2 new file mode 100644 index 000000000000..8f6ff2e27c51 --- /dev/null +++ b/lib/libsys/timer_create.2 @@ -0,0 +1,199 @@ +.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org> +.\" All rights reserved. +.\" +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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. +.\" +.Dd July 15, 2016 +.Dt TIMER_CREATE 2 +.Os +.Sh NAME +.Nm timer_create +.Nd "create a per-process timer (REALTIME)" +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In time.h +.In signal.h +.Ft int +.Fo timer_create +.Fa "clockid_t clockid" "struct sigevent *restrict evp" +.Fa "timer_t *restrict timerid" +.Fc +.Sh DESCRIPTION +The +.Fn timer_create +system call creates a per-process timer using the specified clock, +.Fa clock_id , +as the timing base. +The +.Fn timer_create +system call returns, in the location referenced by +.Fa timerid , +a timer ID of type +.Vt timer_t +used to identify the timer in timer requests. +This timer ID is unique within the calling process until the timer is deleted. +The particular clock, +.Fa clock_id , +is defined in +.In time.h . +The timer whose ID is returned is in a disarmed state upon return from +.Fn timer_create . +.Pp +The +.Fa evp +argument, if +.Pf non- Dv NULL , +points to a +.Vt sigevent +structure. +This structure, +allocated by the application, defines the asynchronous notification to occur +when the timer expires. +.Pp +If +.Fa evp->sigev_notify +is +.Dv SIGEV_SIGNO +or +.Dv SIGEV_THREAD_ID , +the signal specified in +.Fa evp->sigev_signo +will be sent to the calling process +.Pq Dv SIGEV_SIGNO +or to the thread whose LWP ID is +.Fa evp->sigev_notify_thread_id +.Pq Dv SIGEV_THREAD_ID . +The information for the queued signal will include: +.Bl -column ".Va si_value" +.It Sy Member Ta Sy Value +.It Va si_code Ta Dv SI_TIMER +.It Va si_value Ta +the value stored in +.Fa evp->sigev_value +.It Va si_timerid Ta timer ID +.It Va si_overrun Ta timer overrun count +.It Va si_errno Ta +If timer overrun is +.Brq Dv DELAYTIMER_MAX , +an error code defined in +.In errno.h +.El +.Pp +If the +.Fa evp +argument is +.Dv NULL , +the effect is as if the +.Fa evp +argument pointed to a +.Vt sigevent +structure with the +.Va sigev_notify +member having the value +.Dv SIGEV_SIGNAL , +the +.Va sigev_signo +having a default signal number +.Pq Dv SIGALRM , +and the +.Va sigev_value +member having +the value of the timer ID. +.Pp +This implementation supports a +.Fa clock_id +of +.Dv CLOCK_REALTIME , +.Dv CLOCK_TAI , +or +.Dv CLOCK_MONOTONIC . +.Pp +If +.Fa evp->sigev_notify +is +.Dv SIGEV_THREAD +and +.Fa sev->sigev_notify_attributes +is not +.Dv NULL , +if the attribute pointed to by +.Fa sev->sigev_notify_attributes +has +a thread stack address specified by a call to +.Fn pthread_attr_setstack +or +.Fn pthread_attr_setstackaddr , +the results are unspecified if the signal is generated more than once. +.Sh RETURN VALUES +If the call succeeds, +.Fn timer_create +returns zero and updates the location referenced by +.Fa timerid +to a +.Vt timer_t , +which can be passed to the per-process timer calls. +If an error +occurs, the system call returns a value of \-1 +and the global variable +.Va errno +is set to indicate the +error. +The value of +.Fa timerid +is undefined if an error occurs. +.Sh ERRORS +The +.Fn timer_create +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The calling process has already created all of the timers it is allowed by +this implementation. +.It Bq Er EINVAL +The specified clock ID is not supported. +.It Bq Er EINVAL +The specified asynchronous notification method is not supported. +.It Bq Er EFAULT +Any arguments point outside the allocated address space or there is a +memory protection fault. +.El +.Sh SEE ALSO +.Xr clock_getres 2 , +.Xr timer_delete 2 , +.Xr timer_getoverrun 2 , +.Xr sigevent 3 , +.Xr siginfo 3 +.Sh STANDARDS +The +.Fn timer_create +system call conforms to +.St -p1003.1-2004 . +.Sh HISTORY +Support for +.Tn POSIX +per-process timer first appeared in +.Fx 7.0 . diff --git a/lib/libsys/timer_delete.2 b/lib/libsys/timer_delete.2 new file mode 100644 index 000000000000..dbd1a23779ab --- /dev/null +++ b/lib/libsys/timer_delete.2 @@ -0,0 +1,78 @@ +.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org> +.\" All rights reserved. +.\" +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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. +.\" +.Dd September 11, 2000 +.Dt TIMER_DELETE 2 +.Os +.Sh NAME +.Nm timer_delete +.Nd "delete a per-process timer (REALTIME)" +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In time.h +.Ft int +.Fn timer_delete "timer_t timerid" +.Sh DESCRIPTION +The +.Fn timer_delete +system call +deletes the specified timer, +.Fa timerid , +previously created by the +.Xr timer_create 2 +system call. +If the timer is armed when +.Fn timer_delete +is called, the behavior is as if the timer is automatically disarmed before +removal. +Pending signals for the deleted timer are cleared. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn timer_delete +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The timer ID specified by +.Fa timerid +is not a valid timer ID. +.El +.Sh SEE ALSO +.Xr timer_create 2 +.Sh STANDARDS +The +.Fn timer_delete +system call conforms to +.St -p1003.1-2004 . +.Sh HISTORY +Support for +.Tn POSIX +per-process timer first appeared in +.Fx 7.0 . diff --git a/lib/libsys/timer_settime.2 b/lib/libsys/timer_settime.2 new file mode 100644 index 000000000000..08cf2ca17cc7 --- /dev/null +++ b/lib/libsys/timer_settime.2 @@ -0,0 +1,263 @@ +.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org> +.\" All rights reserved. +.\" +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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. +.\" +.Dd September 11, 2000 +.Dt TIMER_SETTIME 2 +.Os +.Sh NAME +.Nm timer_getoverrun , +.Nm timer_gettime , +.Nm timer_settime +.Nd "per-process timers (REALTIME)" +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In time.h +.Ft int +.Fn timer_getoverrun "timer_t timerid" +.Ft int +.Fn timer_gettime "timer_t timerid" "struct itimerspec *value" +.Ft int +.Fo timer_settime +.Fa "timer_t timerid" "int flags" "const struct itimerspec *restrict value" +.Fa "struct itimerspec *restrict ovalue" +.Fc +.Sh DESCRIPTION +The +.Fn timer_gettime +system call stores the amount of time until the specified timer, +.Fa timerid , +expires and the reload value of the timer into the space pointed to by the +.Fa value +argument. +The +.Va it_value +member of this structure contains the amount of time +before the timer expires, or zero if the timer is disarmed. +This value is +returned as the interval until timer expiration, even if the timer was armed +with absolute time. +The +.Va it_interval +member of +.Fa value +contains the reload +value last set by +.Fn timer_settime . +.Pp +The +.Fn timer_settime +system call sets the time until the next expiration of the timer specified +by +.Fa timerid +from the +.Va it_value +member of the +.Fa value +argument and arms the timer if the +.Va it_value +member of +.Fa value +is non-zero. +If the specified timer was already +armed when +.Fn timer_settime +is called, this call resets the time until next expiration to the value +specified. +If the +.Va it_value +member of +.Fa value +is zero, the timer is disarmed. +If the timer is disarmed, then pending signal is removed. +.Pp +If the flag +.Dv TIMER_ABSTIME +is not set in the argument +.Fa flags , +.Fn timer_settime +behaves as if the time until next expiration is set to +be equal to the interval specified by the +.Va it_value +member of +.Fa value . +That is, +the timer expires in +.Va it_value +nanoseconds from when the call is made. +If the flag +.Dv TIMER_ABSTIME +is set in the argument +.Fa flags , +.Fn timer_settime +behaves as if the time until next expiration is set to be equal to the +difference between the absolute time specified by the it_value member of +value and the current value of the clock associated with +.Fa timerid . +That is, the timer expires when the clock reaches the value specified by the +.Va it_value +member of +.Fa value . +If the specified time has already passed, the +system call succeeds and the expiration notification is made. +.Pp +The reload value of the timer is set to the value specified by the +.Va it_interval +member of +.Fa value . +When a timer is armed with a non-zero +.Va it_interval , +a periodic +(or repetitive) timer is specified. +.Pp +Time values that are between two consecutive non-negative integer multiples of +the resolution of the specified timer are rounded up to the larger multiple of +the resolution. +Quantization error will not cause the timer to expire earlier +than the rounded time value. +.Pp +If the argument +.Fa ovalue +is not +.Dv NULL , +the +.Fn timer_settime +system call stores, in the location referenced by +.Fa ovalue , +a value representing +the previous amount of time before the timer would have expired, or zero if the +timer was disarmed, together with the previous timer reload value. +Timers do not +expire before their scheduled time. +.Pp +Only a single signal is queued to the process for a given timer at any point in +time. +When a timer for which a signal is still pending expires, no signal is +queued, and a timer overrun will occur. +When a timer expiration signal is +accepted by a process, the +.Fn timer_getoverrun +system call returns the timer expiration overrun count for the specified timer. +The overrun count returned contains the number of extra timer expirations that +occurred between the time the signal was generated (queued) and when it was +accepted, up to but not including an maximum of +.Brq Dv DELAYTIMER_MAX . +If the number of +such extra expirations is greater than or equal to +.Brq Dv DELAYTIMER_MAX , +then the overrun count is set to +.Brq Dv DELAYTIMER_MAX . +The value returned by +.Fn timer_getoverrun +applies to the most recent expiration signal acceptance for the timer. +If no +expiration signal has been delivered for the timer, the return value of +.Fn timer_getoverrun +is unspecified. +.Sh RETURN VALUES +If the +.Fn timer_getoverrun +system call succeeds, it returns the timer expiration overrun count as explained +above. +Otherwise the value \-1 is returned, and the global variable +.Va errno +is set to indicate the error. +.Pp +.Rv -std timer_gettime timer_settime +.Sh ERRORS +The +.Fn timer_settime +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +A +.Fa value +structure specified a nanosecond value less than zero or greater than +or equal to 1000 million, and the +.Va it_value +member of that structure did not +specify zero seconds and nanoseconds. +.El +.Pp +These system calls may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa timerid +argument does not correspond to an ID returned by +.Fn timer_create +but not yet deleted by +.Fn timer_delete . +.El +.Pp +The +.Fn timer_settime +system call may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Va it_interval +member of +.Fa value +is not zero and the timer was created with +notification by creation of a new thread +.Va ( sigev_sigev_notify +was +.Dv SIGEV_THREAD ) +and a fixed stack address has been set in the thread attribute pointed to by +.Va sigev_notify_attributes . +.El +.Pp +The +.Fn timer_gettime +and +.Fn timer_settime +system calls +may fail if: +.Bl -tag -width Er +.It Bq Er EFAULT +Any arguments point outside the allocated address space or there is a +memory protection fault. +.El +.Sh SEE ALSO +.Xr clock_getres 2 , +.Xr timer_create 2 , +.Xr siginfo 3 +.Sh STANDARDS +The +.Fn timer_getoverrun , +.Fn timer_gettime , +and +.Fn timer_settime +system calls conform to +.St -p1003.1-2004 . +.Sh HISTORY +Support for +.Tn POSIX +per-process timer first appeared in +.Fx 7.0 . diff --git a/lib/libsys/timerfd.2 b/lib/libsys/timerfd.2 new file mode 100644 index 000000000000..ae6cc6f6f49a --- /dev/null +++ b/lib/libsys/timerfd.2 @@ -0,0 +1,347 @@ +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2023 Jake Freeland <jfree@FreeBSD.org> +.\" +.\" 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. +.\" +.Dd June 28, 2024 +.Dt TIMERFD 2 +.Os +.Sh NAME +.Nm timerfd , +.Nm timerfd_create , +.Nm timerfd_gettime , +.Nm timerfd_settime +.Nd timers with file descriptor semantics +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/timerfd.h +.Ft int +.Fo timerfd_create +.Fa "int clockid" +.Fa "int flags" +.Fc +.Ft int +.Fo timerfd_gettime +.Fa "int fd" +.Fa "struct itimerspec *curr_value" +.Fc +.Ft int +.Fo timerfd_settime +.Fa "int fd" +.Fa "int flags" +.Fa "const struct itimerspec *new_value" +.Fa "struct itimerspec *old_value" +.Fc +.Sh DESCRIPTION +The +.Nm +system calls operate on timers, identified by special +.Nm +file descriptors. +These calls are analogous to +.Fn timer_create , +.Fn timer_gettime , +and +.Fn timer_settime +per-process timer functions, but use a +.Nm +descriptor in place of +.Fa timerid . +.Pp +All +.Nm +descriptors possess traditional file descriptor semantics; they may be passed +to other processes, preserved across +.Xr fork 2 , +and monitored via +.Xr kevent 2 , +.Xr poll 2 , +or +.Xr select 2 . +When a +.Nm +descriptor is no longer needed, it may be disposed of using +.Xr close 2 . +.Bl -tag -width "Fn timerfd_settime" +.It Fn timerfd_create +Initialize a +.Nm +object and return its file descriptor. +The +.Fa clockid +argument specifies the clock used as a timing base and may be: +.Pp +.Bl -tag -width "Dv CLOCK_MONOTONIC" -compact +.It Dv CLOCK_REALTIME +Increments as a wall clock should. +.It Dv CLOCK_BOOTTIME +.It Dv CLOCK_MONOTONIC +Increments monotonically in SI seconds. +.It Dv CLOCK_UPTIME +Increments monotonically in SI seconds, but is paused while the system is +suspended. +.El +See +.Xr clock_gettime 2 +for more precise definitions. +.Pp +The +.Fa flags +argument may contain the result of +.Em or Ns 'ing +the following values: +.Pp +.Bl -tag -width "Dv TFD_NONBLOCK" -compact +.It Dv TFD_CLOEXEC +The newly generated file descriptor will close-on-exec. +.It Dv TFD_NONBLOCK +Do not block on read/write operations. +.El +.It Fn timerfd_gettime +Retrieve the current state of the timer denoted by +.Fa fd . +The result is stored in +.Fa curr_value +as a +.Dv struct itimerspec . +The +.Fa it_value +and +.Fa it_interval +members of +.Fa curr_value +represent the relative time until the next expiration and the interval +reload value last set by +.Fn timerfd_settime , +respectively. +.It Fn timerfd_settime +Update the timer denoted by +.Fa fd +with the +.Dv struct itimerspec +in +.Fa new_value . +The +.Fa it_value +member of +.Fa new_value +should contain the amount of time before the timer expires, or zero if the +timer should be disarmed. +The +.Fa it_interval +member should contain the reload time if an interval timer is desired. +.Pp +The previous timer state will be stored in +.Fa old_value +given +.Fa old_value +is not +.Dv NULL . +.Pp +The +.Fa flags +argument may contain the result of +.Em or Ns 'ing +the following values: +.Pp +.Bl -tag -width TFD_TIMER_CANCEL_ON_SET -compact +.It Dv TFD_TIMER_ABSTIME +Expiration will occur at the absolute time provided in +.Fa new_value . +Normally, +.Fa new_value +represents a relative time compared to the timer's +.Fa clockid +clock. +.It Dv TFD_TIMER_CANCEL_ON_SET +If +.Fa clockid +has been set to +.Dv CLOCK_REALTIME +and the realtime clock has experienced a discontinuous jump, +then the timer will be canceled and the next +.Xr read 2 +will fail with +.Dv ECANCELED . +.El +.El +.Pp +File operations have the following semantics: +.Bl -tag -width ioctl +.It Xr read 2 +Transfer the number of timer expirations that have occurred since the last +successful +.Xr read 2 +or +.Fn timerfd_settime +into the output buffer of size +.Vt uint64_t . +If the expiration counter is zero, +.Xr read 2 +blocks until a timer expiration occurs unless +.Dv TFD_NONBLOCK +is set, where +.Dv EAGAIN +is returned. +.It Xr poll 2 +The file descriptor is readable when its timer expiration counter is greater +than zero. +.It Xr ioctl 2 +.Bl -tag -width FIONREAD +.It Dv FIOASYNC int +A non-zero input will set the FASYNC flag. +A zero input will clear the FASYNC flag. +.It Dv FIONBIO int +A non-zero input will set the FNONBLOCK flag. +A zero input will clear the FNONBLOCK flag. +.El +.El +.Sh RETURN VALUES +The +.Fn timerfd_create +system call creates a +.Nm +object and returns its file descriptor. +If an error occurs, -1 is returned and the global variable +.Fa errno +is set to indicate the error. +.Pp +The +.Fn timerfd_gettime +and +.Fn timerfd_settime +system calls return 0 on success. +If an error occurs, -1 is returned and the global variable +.Fa errno +is set to indicate the error. +.Sh ERRORS +The +.Fn timerfd_create +system call fails if: +.Bl -tag -width Er +.It Bq Er EINVAL +The specified +.Fa clockid +is not supported. +.It Bq Er EINVAL +The provided +.Fa flags +are invalid. +.It Bq Er EMFILE +The per-process descriptor table is full. +.It Bq Er ENFILE +The system file table is full. +.It Bq Er ENOMEM +The kernel failed to allocate enough memory for the timer. +.El +.Pp +Both +.Fn timerfd_gettime +and +.Fn timerfd_settime +system calls fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The provided +.Fa fd +is invalid. +.It Bq Er EFAULT +The addresses provided by +.Fa curr_value , +.Fa new_value , +or +.Fa old_value +are invalid. +.It Bq Er EINVAL +The provided +.Fa fd +is valid, but was not generated by +.Fn timerfd_create . +.El +.Pp +The following errors only apply to +.Fn timerfd_settime : +.Bl -tag -width Er +.It Bq Er EINVAL +The provided +.Fa flags +are invalid. +.It Bq Er EINVAL +A nanosecond field in the +.Fa new_value +argument specified a value less than zero, or greater than or equal to 10^9. +.It Bq Er ECANCELED +The timer was created with the clock ID +.Dv CLOCK_REALTIME , +was configured with the +.Dv TFD_TIMER_CANCEL_ON_SET +flag, and the system realtime clock experienced a discontinuous change without +being read. +.El +.Pp +A read from a +.Nm +object fails if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The timer's expiration counter is zero and the +.Nm +object is set for non-blocking I/O. +.It Bq Er ECANCELED +The timer was created with the clock ID +.Dv CLOCK_REALTIME , +was configured with the +.Dv TFD_TIMER_CANCEL_ON_SET +flag, and the system realtime clock experienced a discontinuous change. +.It Bq Er EINVAL +The size of the read buffer is not large enough to hold the +.Vt uint64_t +sized timer expiration counter. +.El +.Sh SEE ALSO +.Xr eventfd 2 , +.Xr kqueue 2 , +.Xr poll 2 , +.Xr read 2 , +.Xr timer_create 2 , +.Xr timer_gettime 2 , +.Xr timer_settime 2 +.Sh STANDARDS +The +.Nm +system calls originated from Linux and are non-standard. +.Sh HISTORY +.An -nosplit +The +.Nm +facility was originally ported to +.Fx Ns 's +Linux compatibility layer by +.An Dmitry Chagin Aq Mt dchagin@FreeBSD.org +in +.Fx 12.0 . +It was revised and adapted to be native by +.An Jake Freeland Aq Mt jfree@FreeBSD.org +in +.Fx 14.0 . diff --git a/lib/libsys/truncate.2 b/lib/libsys/truncate.2 new file mode 100644 index 000000000000..1ab9fc033dd3 --- /dev/null +++ b/lib/libsys/truncate.2 @@ -0,0 +1,167 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd March 30, 2020 +.Dt TRUNCATE 2 +.Os +.Sh NAME +.Nm truncate , +.Nm ftruncate +.Nd truncate or extend a file to a specified length +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn truncate "const char *path" "off_t length" +.Ft int +.Fn ftruncate "int fd" "off_t length" +.Sh DESCRIPTION +The +.Fn truncate +system call +causes the file named by +.Fa path +or referenced by +.Fa fd +to be truncated or extended to +.Fa length +bytes in size. +If the file +was larger than this size, the extra data +is lost. +If the file was smaller than this size, +it will be extended as if by writing bytes +with the value zero. +.Pp +The +.Fn ftruncate +system call causes the file or shared memory object backing the file descriptor +.Fa fd +to be truncated or extended to +.Fa length +bytes in size. +The file descriptor must be a valid file descriptor open for writing. +The file position pointer associated with the file descriptor +.Fa fd +will not be modified. +.Sh RETURN VALUES +.Rv -std +If the file to be modified is not a directory or +a regular file, the +.Fn truncate +call has no effect and returns the value 0. +.Sh ERRORS +The +.Fn truncate +system call +succeeds unless: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named file does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er EACCES +The named file is not writable by the user. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EPERM +The named file has its immutable or append-only flag set, see the +.Xr chflags 2 +manual page for more information. +.It Bq Er EISDIR +The named file is a directory. +.It Bq Er EROFS +The named file resides on a read-only file system. +.It Bq Er ETXTBSY +The file is a pure procedure (shared text) file that is being executed. +.It Bq Er EFBIG +The +.Fa length +argument was greater than the maximum file size. +.It Bq Er EINVAL +The +.Fa length +argument was less than 0. +.It Bq Er EIO +An I/O error occurred updating the inode. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.El +.Pp +The +.Fn ftruncate +system call +succeeds unless: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument +is not a valid descriptor. +.It Bq Er EINVAL +The +.Fa fd +argument +references a file descriptor that is not a regular file or shared memory object. +.It Bq Er EINVAL +The +.Fa fd +descriptor +is not open for writing. +.El +.Sh SEE ALSO +.Xr chflags 2 , +.Xr open 2 , +.Xr shm_open 2 +.Sh HISTORY +The +.Fn truncate +and +.Fn ftruncate +system calls appeared in +.Bx 4.2 . +.Sh BUGS +These calls should be generalized to allow ranges +of bytes in a file to be discarded. +.Pp +Historically, the use of +.Fn truncate +or +.Fn ftruncate +to extend a file was not portable, but this behavior became required in +.St -p1003.1-2008 . diff --git a/lib/libsys/umask.2 b/lib/libsys/umask.2 new file mode 100644 index 000000000000..05f5ca090e55 --- /dev/null +++ b/lib/libsys/umask.2 @@ -0,0 +1,85 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd June 4, 1993 +.Dt UMASK 2 +.Os +.Sh NAME +.Nm umask +.Nd set file creation mode mask +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/stat.h +.Ft mode_t +.Fn umask "mode_t numask" +.Sh DESCRIPTION +The +.Fn umask +routine sets the process's file mode creation mask to +.Fa numask +and returns the previous value of the mask. +The 9 low-order +access permission +bits of +.Fa numask +are used by system calls, including +.Xr open 2 , +.Xr mkdir 2 , +and +.Xr mkfifo 2 , +to turn off corresponding bits +requested in file mode. +(See +.Xr chmod 2 ) . +This clearing allows each user to restrict the default access +to his files. +.Pp +The default mask value is S_IWGRP|S_IWOTH (022, write access for the +owner only). +Child processes inherit the mask of the calling process. +.Sh RETURN VALUES +The previous value of the file mode mask is returned by the call. +.Sh ERRORS +The +.Fn umask +system call is always successful. +.Sh SEE ALSO +.Xr chmod 2 , +.Xr mkfifo 2 , +.Xr mknod 2 , +.Xr open 2 +.Sh STANDARDS +The +.Fn umask +system call is expected to conform to +.St -p1003.1-90 . +.Sh HISTORY +The +.Fn umask +function appeared in +.At v7 . diff --git a/lib/libsys/undelete.2 b/lib/libsys/undelete.2 new file mode 100644 index 000000000000..ef6b43926fc6 --- /dev/null +++ b/lib/libsys/undelete.2 @@ -0,0 +1,104 @@ +.\" Copyright (c) 1994 +.\" Jan-Simon Pendry +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd March 30, 2020 +.Dt UNDELETE 2 +.Os +.Sh NAME +.Nm undelete +.Nd attempt to recover a deleted file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn undelete "const char *path" +.Sh DESCRIPTION +The +.Fn undelete +system call attempts to recover the deleted file named by +.Fa path . +Currently, this works only when the named object +is a whiteout in a union file system. +The system call removes the whiteout causing +any objects in a lower layer of the +union stack to become visible once more. +.Pp +Eventually, the +.Fn undelete +functionality may be expanded to other file systems able to recover +deleted files such as the log-structured file system. +.Sh RETURN VALUES +.Rv -std undelete +.Sh ERRORS +The +.Fn undelete +succeeds unless: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er EEXIST +The path does not reference a whiteout. +.It Bq Er ENOENT +The named whiteout does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er EACCES +Write permission is denied on the directory containing the name +to be undeleted. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EPERM +The directory containing the name is marked sticky, +and the containing directory is not owned by the effective user ID. +.It Bq Er EINVAL +The last component of the path is +.Ql .. . +.It Bq Er EIO +An I/O error occurred while updating the directory entry. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.It Bq Er EROFS +The name resides on a read-only file system. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.El +.Sh SEE ALSO +.Xr unlink 2 , +.Xr mount_unionfs 8 +.Sh HISTORY +The +.Fn undelete +system call first appeared in +.Bx 4.4 Lite . diff --git a/lib/libsys/unlink.2 b/lib/libsys/unlink.2 new file mode 100644 index 000000000000..be2b44855daf --- /dev/null +++ b/lib/libsys/unlink.2 @@ -0,0 +1,281 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd February 23, 2021 +.Dt UNLINK 2 +.Os +.Sh NAME +.Nm unlink , +.Nm unlinkat , +.Nm funlinkat +.Nd remove directory entry +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn unlink "const char *path" +.Ft int +.Fn unlinkat "int dfd" "const char *path" "int flag" +.Ft int +.Fn funlinkat "int dfd" "const char *path" "int fd" "int flag" +.Sh DESCRIPTION +The +.Fn unlink +system call +removes the link named by +.Fa path +from its directory and decrements the link count of the +file which was referenced by the link. +If that decrement reduces the link count of the file +to zero, +and no process has the file open, then +all resources associated with the file are reclaimed. +If one or more process have the file open when the last link is removed, +the link is removed, but the removal of the file is delayed until +all references to it have been closed. +The +.Fa path +argument +may not be a directory. +.Pp +The +.Fn unlinkat +system call is equivalent to +.Fn unlink +or +.Fn rmdir +except in the case where +.Fa path +specifies a relative path. +In this case the directory entry to be removed is determined +relative to the directory associated with the file descriptor +.Fa dfd +instead of the current working directory. +.Pp +The values for +.Fa flag +are constructed by a bitwise-inclusive OR of flags from the following list, +defined in +.In fcntl.h : +.Bl -tag -width indent +.It Dv AT_REMOVEDIR +Remove the directory entry specified by +.Fa fd +and +.Fa path +as a directory, not a normal file. +.It Dv AT_RESOLVE_BENEATH +Only walk paths below the directory specified by the +.Ar fd +descriptor. +See the description of the +.Dv O_RESOLVE_BENEATH +flag in the +.Xr open 2 +manual page. +.El +.Pp +If +.Fn unlinkat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is +identical to a call to +.Fa unlink +or +.Fa rmdir +respectively, depending on whether or not the +.Dv AT_REMOVEDIR +bit is set in flag. +.Pp +The +.Fn funlinkat +system call can be used to unlink an already-opened file, unless that +file has been replaced since it was opened. +It is equivalent to +.Fn unlinkat +in the case where +.Fa path +is already open as the file descriptor +.Fa fd . +Otherwise, the path will not be removed and an error will be returned. +The +.Fa fd +can be set the +.Dv FD_NONE . +In that case +.Fn funlinkat +behaves exactly like +.Fn unlinkat . +.Sh RETURN VALUES +.Rv -std unlink +.Sh ERRORS +The +.Fn unlink +succeeds unless: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er EISDIR +The named file is a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named file does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er EACCES +Write permission is denied on the directory containing the link +to be removed. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EPERM +The named file is a directory. +.It Bq Er EPERM +The named file has its immutable, undeletable or append-only flag set, see the +.Xr chflags 2 +manual page for more information. +.It Bq Er EPERM +The parent directory of the named file has its immutable or append-only flag +set. +.It Bq Er EPERM +The directory containing the file is marked sticky, +and neither the containing directory nor the file to be removed +are owned by the effective user ID. +.It Bq Er EIO +An I/O error occurred while deleting the directory entry +or deallocating the inode. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.It Bq Er EROFS +The named file resides on a read-only file system. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.It Bq Er ENOSPC +On file systems supporting copy-on-write or snapshots, there was not enough +free space to record metadata for the delete operation of the file. +.El +.Pp +In addition to the errors returned by the +.Fn unlink , +the +.Fn unlinkat +may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er ENOTEMPTY +The +.Fa flag +parameter has the +.Dv AT_REMOVEDIR +bit set and the +.Fa path +argument names a directory that is not an empty directory, +or there are hard links to the directory other than dot or +a single entry in dot-dot. +.It Bq Er ENOTDIR +The +.Fa flag +parameter has the +.Dv AT_REMOVEDIR +bit set and +.Fa path +does not name a directory. +.It Bq Er EINVAL +The value of the +.Fa flag +argument is not valid. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.It Bq Er ENOTCAPABLE +.Fa path +is an absolute path, +or contained a ".." component leading to a +directory outside of the directory hierarchy specified by +.Fa fd , +and the process is in capability mode or the +.Dv AT_RESOLVE_BENEATH +flag was specified. +.El +.Pp +In addition to the errors returned by +.Fn unlinkat , +.Fn funlinkat +may fail if: +.Bl -tag -width Er +.It Bq Er EDEADLK +The file descriptor is not associated with the path. +.El +.Sh SEE ALSO +.Xr chflags 2 , +.Xr close 2 , +.Xr link 2 , +.Xr rmdir 2 , +.Xr symlink 7 +.Sh STANDARDS +The +.Fn unlinkat +system call follows The Open Group Extended API Set 2 specification. +.Sh HISTORY +The +.Fn unlink +function appeared in +.At v1 . +The +.Fn unlinkat +system call appeared in +.Fx 8.0 . +The +.Fn funlinkat +system call appeared in +.Fx 13.0 . +.Pp +The +.Fn unlink +system call traditionally allows the super-user to unlink directories which +can damage the file system integrity. +This implementation no longer permits it. diff --git a/lib/libsys/usleep.3 b/lib/libsys/usleep.3 new file mode 100644 index 000000000000..c8c8df24d309 --- /dev/null +++ b/lib/libsys/usleep.3 @@ -0,0 +1,77 @@ +.\" Copyright (c) 1986, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd February 11, 2021 +.Dt USLEEP 3 +.Os +.Sh NAME +.Nm usleep +.Nd suspend thread execution for an interval measured in microseconds +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn usleep "useconds_t microseconds" +.Sh DESCRIPTION +The +.Fn usleep +function suspends execution of the calling thread until either +.Fa microseconds +microseconds have elapsed or a signal is delivered to the thread and its +action is to invoke a signal-catching function or to terminate the +process. +System activity may lengthen the sleep by an indeterminate amount. +.Pp +This function is implemented using +.Xr nanosleep 2 +by pausing for +.Fa microseconds +microseconds or until a signal occurs. +Consequently, in this implementation, +sleeping has no effect on the state of process timers, +and there is no special handling for SIGALRM. +.Sh RETURN VALUES +.Rv -std usleep +.Sh ERRORS +The +.Fn usleep +function +will fail if: +.Bl -tag -width Er +.It Bq Er EINTR +A signal was delivered to the calling thread and its +action was to invoke a signal-catching function. +.El +.Sh SEE ALSO +.Xr nanosleep 2 , +.Xr sleep 3 +.Sh HISTORY +The +.Fn usleep +function appeared in +.Bx 4.3 . diff --git a/lib/libsys/utimensat.2 b/lib/libsys/utimensat.2 new file mode 100644 index 000000000000..e2c5a8b90939 --- /dev/null +++ b/lib/libsys/utimensat.2 @@ -0,0 +1,307 @@ +.\" $NetBSD: utimes.2,v 1.13 1999/03/22 19:45:11 garbled Exp $ +.\" +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" Copyright (c) 2012, Jilles Tjoelker +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd June 12, 2022 +.Dt UTIMENSAT 2 +.Os +.Sh NAME +.Nm futimens , +.Nm utimensat +.Nd set file access and modification times +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/stat.h +.Ft int +.Fn futimens "int fd" "const struct timespec times[2]" +.Ft int +.Fo utimensat +.Fa "int fd" +.Fa "const char *path" +.Fa "const struct timespec times[2]" +.Fa "int flag" +.Fc +.Sh DESCRIPTION +The access and modification times of the file named by +.Fa path +or referenced by +.Fa fd +are changed as specified by the argument +.Fa times . +The inode-change-time of the file is set to the current time. +.Pp +If +.Fa path +specifies a relative path, +it is relative to the current working directory if +.Fa fd +is +.Dv AT_FDCWD +and otherwise relative to the directory associated with the file descriptor +.Fa fd . +.Pp +The +.Va tv_nsec +field of a +.Vt timespec +structure +can be set to the special value +.Dv UTIME_NOW +to set the current time, or to +.Dv UTIME_OMIT +to leave the time unchanged. +In either case, the +.Va tv_sec +field is ignored. +.Pp +If +.Fa times +is +.No non- Ns Dv NULL , +it is assumed to point to an array of two timespec structures. +The access time is set to the value of the first element, and the +modification time is set to the value of the second element. +For file systems that support file birth (creation) times (such as +.Dv UFS2 ) , +the birth time will be set to the value of the second element +if the second element is older than the currently set birth time. +To set both a birth time and a modification time, +two calls are required; the first to set the birth time +and the second to set the (presumably newer) modification time. +Ideally a new system call will be added that allows the setting +of all three times at once. +If +.Fa times +is +.Dv NULL , +this is equivalent to passing +a pointer to an array of two timespec structures +with both +.Va tv_nsec +fields set to +.Dv UTIME_NOW . +.Pp +If both +.Va tv_nsec +fields are +.Dv UTIME_OMIT , +the timestamps remain unchanged and +no permissions are needed for the file itself, +although search permissions may be required for the path prefix. +The call may or may not succeed if the named file does not exist. +.Pp +If both +.Va tv_nsec +fields are +.Dv UTIME_NOW , +the caller must be the owner of the file, have permission to +write the file, or be the super-user. +.Pp +For all other values of the timestamps, +the caller must be the owner of the file or be the super-user. +.Pp +The values for the +.Fa flag +argument of the +.Fn utimensat +system call +are constructed by a bitwise-inclusive OR of flags from the following list, +defined in +.In fcntl.h : +.Bl -tag -width indent +.It Dv AT_SYMLINK_NOFOLLOW +If +.Fa path +names a symbolic link, the symbolic link's times are changed. +By default, +.Fn utimensat +changes the times of the file referenced by the symbolic link. +.It Dv AT_RESOLVE_BENEATH +Only walk paths below the directory specified by the +.Ar fd +descriptor. +See the description of the +.Dv O_RESOLVE_BENEATH +flag in the +.Xr open 2 +manual page. +.It Dv AT_EMPTY_PATH +If the +.Fa path +argument is an empty string, operate on the file or directory +referenced by the descriptor +.Fa fd . +If +.Fa fd +is equal to +.Dv AT_FDCWD , +operate on the current working directory. +.El +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +These system calls will fail if: +.Bl -tag -width Er +.It Bq Er EACCES +The +.Fa times +argument is +.Dv NULL , +or both +.Va tv_nsec +values are +.Dv UTIME_NOW , +and the effective user ID of the process does not +match the owner of the file, and is not the super-user, and write +access is denied. +.It Bq Er EFAULT +The +.Fa times +argument +points outside the process's allocated address space. +.It Bq Er EINVAL +The +.Va tv_nsec +component of at least one of the values specified by the +.Fa times +argument has a value less than 0 or greater than 999999999 and is not equal to +.Dv UTIME_NOW +or +.Dv UTIME_OMIT . +.It Bq Er EIO +An I/O error occurred while reading or writing the affected inode. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.It Bq Er EPERM +The +.Fa times +argument is not +.Dv NULL +nor are both +.Va tv_nsec +values +.Dv UTIME_NOW , +nor are both +.Va tv_nsec +values +.Dv UTIME_OMIT +and the calling process's effective user ID +does not match the owner of the file and is not the super-user. +.It Bq Er EPERM +The named file has its immutable or append-only flag set, see the +.Xr chflags 2 +manual page for more information. +.It Bq Er EROFS +The file system containing the file is mounted read-only. +.El +.Pp +The +.Fn futimens +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument +does not refer to a valid descriptor. +.El +.Pp +The +.Fn utimensat +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded +.Dv NAME_MAX +characters, or an entire path name exceeded +.Dv PATH_MAX +characters. +.It Bq Er ENOENT +The named file does not exist. +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.It Bq Er ENOTCAPABLE +.Fa path +is an absolute path, +or contained a ".." component leading to a +directory outside of the directory hierarchy specified by +.Fa fd , +and the process is in capability mode or the +.Dv AT_RESOLVE_BENEATH +flag was specified. +.El +.Sh SEE ALSO +.Xr chflags 2 , +.Xr stat 2 , +.Xr symlink 2 , +.Xr utimes 2 , +.Xr utime 3 , +.Xr symlink 7 +.Sh STANDARDS +The +.Fn futimens +and +.Fn utimensat +system calls are expected to conform to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn futimens +and +.Fn utimensat +system calls appeared in +.Fx 10.3 . diff --git a/lib/libsys/utimes.2 b/lib/libsys/utimes.2 new file mode 100644 index 000000000000..413e107a90c5 --- /dev/null +++ b/lib/libsys/utimes.2 @@ -0,0 +1,261 @@ +.\" $NetBSD: utimes.2,v 1.13 1999/03/22 19:45:11 garbled Exp $ +.\" +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd March 30, 2020 +.Dt UTIMES 2 +.Os +.Sh NAME +.Nm utimes , +.Nm lutimes , +.Nm futimes , +.Nm futimesat +.Nd set file access and modification times +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/time.h +.Ft int +.Fn utimes "const char *path" "const struct timeval *times" +.Ft int +.Fn lutimes "const char *path" "const struct timeval *times" +.Ft int +.Fn futimes "int fd" "const struct timeval *times" +.Ft int +.Fn futimesat "int fd" "const char *path" "const struct timeval times[2]" +.Sh DESCRIPTION +.Bf -symbolic +These interfaces are obsoleted by +.Xr futimens 2 +and +.Xr utimensat 2 +because they are not accurate to nanoseconds. +.Ef +.Pp +The access and modification times of the file named by +.Fa path +or referenced by +.Fa fd +are changed as specified by the argument +.Fa times . +.Pp +If +.Fa times +is +.Dv NULL , +the access and modification times are set to the current time. +The caller must be the owner of the file, have permission to +write the file, or be the super-user. +.Pp +If +.Fa times +is +.No non- Ns Dv NULL , +it is assumed to point to an array of two timeval structures. +The access time is set to the value of the first element, and the +modification time is set to the value of the second element. +For file systems that support file birth (creation) times (such as +.Dv UFS2 ) , +the birth time will be set to the value of the second element +if the second element is older than the currently set birth time. +To set both a birth time and a modification time, +two calls are required; the first to set the birth time +and the second to set the (presumably newer) modification time. +Ideally a new system call will be added that allows the setting +of all three times at once. +The caller must be the owner of the file or be the super-user. +.Pp +In either case, the inode-change-time of the file is set to the current +time. +.Pp +The +.Fn lutimes +system call +is like +.Fn utimes +except in the case where the named file is a symbolic link, +in which case +.Fn lutimes +changes the access and modification times of the link, +while +.Fn utimes +changes the times of the file the link references. +.Pp +The +.Fn futimesat +system call is equivalent to +.Fn utimes +except in the case where +.Fa path +specifies a relative path. +In this case the access and modification time +is set to that of a file relative to the directory associated with the file +descriptor +.Fa fd +instead of the current working directory. +If +.Fn futimesat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior +is identical to a call to +.Fn utimes . +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +All of the system call will fail if: +.Bl -tag -width Er +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er EACCES +The +.Fa times +argument is +.Dv NULL +and the effective user ID of the process does not +match the owner of the file, and is not the super-user, and write +access is denied. +.It Bq Er EFAULT +The +.Fa path +or +.Fa times +argument +points outside the process's allocated address space. +.It Bq Er EFAULT +The +.Fa times +argument +points outside the process's allocated address space. +.It Bq Er EINVAL +The +.Va tv_usec +component of at least one of the values specified by the +.Fa times +argument has a value less than 0 or greater than 999999. +.It Bq Er EIO +An I/O error occurred while reading or writing the affected inode. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded +.Dv NAME_MAX +characters, or an entire path name exceeded +.Dv PATH_MAX +characters. +.It Bq Er ENOENT +The named file does not exist. +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er EPERM +The +.Fa times +argument is not +.Dv NULL +and the calling process's effective user ID +does not match the owner of the file and is not the super-user. +.It Bq Er EPERM +The named file has its immutable or append-only flags set. +See the +.Xr chflags 2 +manual page for more information. +.It Bq Er EROFS +The file system containing the file is mounted read-only. +.El +.Pp +The +.Fn futimes +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument +does not refer to a valid descriptor. +.El +.Pp +In addition to the errors returned by the +.Fn utimes , +the +.Fn futimesat +may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El +.Sh SEE ALSO +.Xr chflags 2 , +.Xr stat 2 , +.Xr utimensat 2 , +.Xr utime 3 +.Sh STANDARDS +The +.Fn utimes +function is expected to conform to +.St -xpg4.2 . +The +.Fn futimesat +system call follows The Open Group Extended API Set 2 specification +but was replaced by +.Fn utimensat +in +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn utimes +system call appeared in +.Bx 4.2 . +The +.Fn futimes +and +.Fn lutimes +system calls first appeared in +.Fx 3.0 . +The +.Fn futimesat +system call appeared in +.Fx 8.0 . diff --git a/lib/libsys/utrace.2 b/lib/libsys/utrace.2 new file mode 100644 index 000000000000..f18e65d81a59 --- /dev/null +++ b/lib/libsys/utrace.2 @@ -0,0 +1,78 @@ +.\" $NetBSD: utrace.2,v 1.11 2003/04/24 12:17:49 wiz Exp $ +.\" +.\" Copyright (c) 2000 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry <g.mcgarry@ieee.org>. +.\" +.\" 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 ``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 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. +.\" +.Dd December 11, 2015 +.Dt UTRACE 2 +.Os +.Sh NAME +.Nm utrace +.Nd insert user record in ktrace log +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/time.h +.In sys/uio.h +.In sys/ktrace.h +.Ft int +.Fn utrace "const void *addr" "size_t len" +.Sh DESCRIPTION +Adds a record to the process trace with information supplied by user. +The record contains +.Fa len +bytes from memory pointed to by +.Fa addr . +This call only has an effect if the calling process is being traced. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINVAL +Specified data length +.Fa len +was bigger than +.Dv KTR_USER_MAXLEN . +.It Bq Er ENOMEM +Insufficient memory to honor the request. +.It Bq Er ENOSYS +Currently running kernel was compiled without +.Xr ktrace 2 +support +.Pq Cd "options KTRACE" . +.El +.Sh SEE ALSO +.Xr kdump 1 , +.Xr ktrace 1 , +.Xr truss 1 , +.Xr ktrace 2 , +.Xr sysdecode_utrace 3 +.Sh HISTORY +The +.Fn utrace +system call first appeared in +.Fx 2.2 . diff --git a/lib/libsys/uuidgen.2 b/lib/libsys/uuidgen.2 new file mode 100644 index 000000000000..aa5362947300 --- /dev/null +++ b/lib/libsys/uuidgen.2 @@ -0,0 +1,140 @@ +.\" Copyright (c) 2002 Marcel Moolenaar +.\" All rights reserved. +.\" +.\" 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 ``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 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. +.\" +.Dd May 26, 2002 +.Dt UUIDGEN 2 +.Os +.Sh NAME +.Nm uuidgen +.Nd generate universally unique identifiers +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/uuid.h +.Ft int +.Fn uuidgen "struct uuid *store" "int count" +.Sh DESCRIPTION +The +.Fn uuidgen +system call generates +.Fa count +universally unique identifiers (UUIDs) and writes them to the buffer +pointed to by +.Fa store . +The identifiers are generated according to the syntax and semantics of the +DCE version 1 variant of universally unique identifiers. +See below for a more in-depth description of the identifiers. +When no IEEE 802 +address is available for the node field, a random multicast address is +generated for each invocation of the system call. +According to the algorithm of generating time-based UUIDs, this will also +force a new random clock sequence, thereby increasing the likelihood for +the identifier to be unique. +.Pp +When multiple identifiers are to be generated, the +.Fn uuidgen +system call will generate a set of identifiers that is dense in such a way +that there is no identifier that is larger than the smallest identifier in the +set and smaller than the largest identifier in the set and that is not already +in the set. +.Pp +Universally unique identifiers, also known as globally unique identifiers +(GUIDs), have a binary representation of 128-bits. +The grouping and meaning of these bits is described by the following +structure and its description of the fields that follow it: +.Bd -literal +struct uuid { + uint32_t time_low; + uint16_t time_mid; + uint16_t time_hi_and_version; + uint8_t clock_seq_hi_and_reserved; + uint8_t clock_seq_low; + uint8_t node[_UUID_NODE_LEN]; +}; +.Ed +.Bl -tag -width ".Va clock_seq_hi_and_reserved" +.It Va time_low +The least significant 32 bits of a 60-bit timestamp. +This field is stored in the native byte-order. +.It Va time_mid +The least significant 16 bits of the most significant 28 bits of the 60-bit +timestamp. +This field is stored in the native byte-order. +.It Va time_hi_and_version +The most significant 12 bits of the 60-bit timestamp multiplexed with a 4-bit +version number. +The version number is stored in the most significant 4 bits of the 16-bit +field. +This field is stored in the native byte-order. +.It Va clock_seq_hi_and_reserved +The most significant 6 bits of a 14-bit sequence number multiplexed with a +2-bit variant value. +Note that the width of the variant value is determined by the variant itself. +Identifiers generated by the +.Fn uuidgen +system call have variant value 10b. +the variant value is stored in the most significant bits of the field. +.It Va clock_seq_low +The least significant 8 bits of a 14-bit sequence number. +.It Va node +The 6-byte IEEE 802 (MAC) address of one of the interfaces of the node. +If no such interface exists, a random multi-cast address is used instead. +.El +.Pp +The binary representation is sensitive to byte ordering. +Any multi-byte field is to be stored in the local or native byte-order and +identifiers must be converted when transmitted to hosts that do not agree +on the byte-order. +The specification does not however document what this means in concrete +terms and is otherwise beyond the scope of this system call. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn uuidgen +system call can fail with: +.Bl -tag -width Er +.It Bq Er EFAULT +The buffer pointed to by +.Fa store +could not be written to for any or all identifiers. +.It Bq Er EINVAL +The +.Fa count +argument is less than 1 or larger than the hard upper limit of 2048. +.El +.Sh SEE ALSO +.Xr uuidgen 1 , +.Xr uuid 3 +.Sh STANDARDS +The identifiers are represented and generated in conformance with the DCE 1.1 +RPC specification. +The +.Fn uuidgen +system call is itself not part of the specification. +.Sh HISTORY +The +.Fn uuidgen +system call first appeared in +.Fx 5.0 . diff --git a/lib/libsys/vfork.2 b/lib/libsys/vfork.2 new file mode 100644 index 000000000000..cb17d02bc8d2 --- /dev/null +++ b/lib/libsys/vfork.2 @@ -0,0 +1,142 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd May 22, 2016 +.Dt VFORK 2 +.Os +.Sh NAME +.Nm vfork +.Nd create a new process without copying the address space +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft pid_t +.Fn vfork void +.Sh DESCRIPTION +.Bf -symbolic +Since this function is hard to use correctly from application software, +it is recommended to use +.Xr posix_spawn 3 +or +.Xr fork 2 +instead. +.Ef +.Pp +The +.Fn vfork +system call +can be used to create new processes without fully copying the address +space of the old process, which is inefficient in a paged +environment. +It is useful when the purpose of +.Xr fork 2 +would have been to create a new system context for an +.Xr execve 2 . +The +.Fn vfork +system call +differs from +.Xr fork 2 +in that the child borrows the parent process's address space and the +calling thread's stack +until a call to +.Xr execve 2 +or an exit (either by a call to +.Xr _exit 2 +or abnormally). +The calling thread is suspended while the child is using its resources. +Other threads continue to run. +.Pp +The +.Fn vfork +system call +returns 0 in the child's context and (later) the pid of the child in +the parent's context. +.Pp +Many problems can occur when replacing +.Xr fork 2 +with +.Fn vfork . +For example, it does not work to return while running in the child's context +from the procedure that called +.Fn vfork +since the eventual return from +.Fn vfork +would then return to a no longer existent stack frame. +Also, changing process state which is partially implemented in user space +such as signal handlers with +.Xr libthr 3 +will corrupt the parent's state. +.Pp +Be careful, also, to call +.Xr _exit 2 +rather than +.Xr exit 3 +if you cannot +.Xr execve 2 , +since +.Xr exit 3 +will flush and close standard I/O channels, and thereby mess up the +parent processes standard I/O data structures. +(Even with +.Xr fork 2 +it is wrong to call +.Xr exit 3 +since buffered data would then be flushed twice.) +.Sh RETURN VALUES +Same as for +.Xr fork 2 . +.Sh SEE ALSO +.Xr _exit 2 , +.Xr execve 2 , +.Xr fork 2 , +.Xr rfork 2 , +.Xr sigaction 2 , +.Xr wait 2 , +.Xr exit 3 , +.Xr posix_spawn 3 +.Sh HISTORY +The +.Fn vfork +system call appeared in +.Bx 3 . +.Sh BUGS +To avoid a possible deadlock situation, +processes that are children in the middle +of a +.Fn vfork +are never sent +.Dv SIGTTOU +or +.Dv SIGTTIN +signals; rather, +output or +.Xr ioctl 2 +calls +are allowed +and input attempts result in an end-of-file indication. diff --git a/lib/libsys/wait.2 b/lib/libsys/wait.2 new file mode 100644 index 000000000000..eeddf77aeac7 --- /dev/null +++ b/lib/libsys/wait.2 @@ -0,0 +1,693 @@ +.\" Copyright (c) 1980, 1991, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd June 19, 2025 +.Dt WAIT 2 +.Os +.Sh NAME +.Nm wait , +.Nm waitid , +.Nm waitpid , +.Nm wait3 , +.Nm wait4 , +.Nm wait6 +.Nd wait for processes to change status +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/wait.h +.Ft pid_t +.Fn wait "int *status" +.Ft pid_t +.Fn waitpid "pid_t wpid" "int *status" "int options" +.In signal.h +.Ft int +.Fn waitid "idtype_t idtype" "id_t id" "siginfo_t *info" "int options" +.In sys/time.h +.In sys/resource.h +.Ft pid_t +.Fn wait3 "int *status" "int options" "struct rusage *rusage" +.Ft pid_t +.Fn wait4 "pid_t wpid" "int *status" "int options" "struct rusage *rusage" +.Ft pid_t +.Fo wait6 +.Fa "idtype_t idtype" "id_t id" +.Fa "int *status" +.Fa "int options" +.Fa "struct __wrusage *wrusage" +.Fa "siginfo_t *infop" +.Fc +.Sh DESCRIPTION +The +.Fn wait +function suspends execution of its calling thread until +.Fa status +information is available for a child process +or a signal is received. +On return from a successful +.Fn wait +call, +the +.Fa status +area contains information about the process that reported a status change +as defined below. +.Pp +The +.Fn wait4 +and +.Fn wait6 +system calls provide a more general interface for programs +that need to wait for specific child processes, +that need resource utilization statistics accumulated by child processes, +or that require options. +The other wait functions are implemented using either +.Fn wait4 +or +.Fn wait6 . +.Pp +The +.Fn wait6 +function is the most general function in this family and its distinct +features are: +.Pp +All of the desired process statuses to be waited on must be explicitly +specified in +.Fa options . +The +.Fn wait , +.Fn waitpid , +.Fn wait3 , +and +.Fn wait4 +functions all implicitly wait for exited and trapped processes, +but the +.Fn waitid +and +.Fn wait6 +functions require the corresponding +.Dv WEXITED +and +.Dv WTRAPPED +flags to be explicitly specified. +This allows waiting for processes which have experienced other +status changes without having to also handle the exit status from +terminated processes. +.Pp +The +.Fn wait6 +function accepts a +.Fa wrusage +argument which points to a structure defined as: +.Bd -literal +struct __wrusage { + struct rusage wru_self; + struct rusage wru_children; +}; +.Ed +.Pp +This allows the calling process to collect resource usage statistics +from both its own child process as well as from its grand children. +When no resource usage statistics are needed this pointer can be +.Dv NULL . +.Pp +The last argument +.Fa infop +must be either +.Dv NULL +or a pointer to a +.Fa siginfo_t +structure. +If +.Pf non- Dv NULL , +the structure is filled with the same data as for a +.Dv SIGCHLD +signal delivered when the process changed state. +.Pp +The set of child processes to be queried is specified by the arguments +.Fa idtype +and +.Fa id . +The separate +.Fa idtype +and +.Fa id +arguments support many other types of +identifiers in addition to process IDs and process group IDs. +.Bl -bullet -offset indent +.It +If +.Fa idtype +is +.Dv P_PID , +.Fn waitid +and +.Fn wait6 +wait for the child process with a process ID equal to +.Dv (pid_t)id . +.It +If +.Fa idtype +is +.Dv P_PGID , +.Fn waitid +and +.Fn wait6 +wait for the child process with a process group ID equal to +.Dv (pid_t)id . +.It +If +.Fa idtype +is +.Dv P_ALL , +.Fn waitid +and +.Fn wait6 +wait for any child process and the +.Dv id +is ignored. +.It +If +.Fa idtype +is +.Dv P_PID +or +.Dv P_PGID +and the +.Dv id +is zero, +.Fn waitid +and +.Fn wait6 +wait for any child process in the same process group as the caller. +.El +.Pp +Non-standard identifier types supported by this +implementation of +.Fn waitid +and +.Fn wait6 +are: +.Bl -tag -width P_JAILID +.It Dv P_UID +Wait for processes whose effective user ID is equal to +.Dv (uid_t) Fa id . +.It Dv P_GID +Wait for processes whose effective group ID is equal to +.Dv (gid_t) Fa id . +.It Dv P_SID +Wait for processes whose session ID is equal to +.Fa id . +.\" This is just how sessions work, not sure this needs to be documented here +If the child process started its own session, +its session ID will be the same as its process ID. +Otherwise the session ID of a child process will match the caller's session ID. +.It Dv P_JAILID +Waits for processes within a jail whose jail identifier is equal to +.Fa id . +.El +.Pp +For the +.Fn waitpid +and +.Fn wait4 +functions, the single +.Fa wpid +argument specifies the set of child processes for which to wait. +.Bl -bullet -offset indent +.It +If +.Fa wpid +is -1, the call waits for any child process. +.It +If +.Fa wpid +is 0, +the call waits for any child process in the process group of the caller. +.It +If +.Fa wpid +is greater than zero, the call waits for the process with process ID +.Fa wpid . +.It +If +.Fa wpid +is less than -1, the call waits for any process whose process group ID +equals the absolute value of +.Fa wpid . +.El +.Pp +The +.Fa status +argument is defined below. +.Pp +The +.Fa options +argument contains the bitwise OR of any of the following options. +.Bl -tag -width WCONTINUED +.It Dv WCONTINUED +Report the status of selected processes that +have continued from a job control stop by receiving a +.Dv SIGCONT +signal. +.Xr ptrace 2 +can also cause a process to be continued, when a +.Dv PT_DETACH +request is issued to detach the debugger. +.It Dv WNOHANG +Do not block when +there are no processes wishing to report status. +.It Dv WUNTRACED +Report the status of selected processes which are stopped due to a +.Dv SIGTTIN , SIGTTOU , SIGTSTP , +or +.Dv SIGSTOP +signal. +.It Dv WSTOPPED +An alias for +.Dv WUNTRACED . +.It Dv WTRAPPED +Report the status of selected processes which are being traced via +.Xr ptrace 2 +and have trapped or reached a breakpoint. +This flag is implicitly set for the functions +.Fn wait , +.Fn waitpid , +.Fn wait3 , +and +.Fn wait4 . +.br +For the +.Fn waitid +and +.Fn wait6 +functions, the flag has to be explicitly included in +.Fa options +if status reports from trapped processes are expected. +.It Dv WEXITED +Report the status of selected processes which have terminated. +This flag is implicitly set for the functions +.Fn wait , +.Fn waitpid , +.Fn wait3 , +and +.Fn wait4 . +.br +For the +.Fn waitid +and +.Fn wait6 +functions, the flag has to be explicitly included in +.Fa options +if status reports from terminated processes are expected. +.It Dv WNOWAIT +Keep the process whose status is returned in a waitable state. +The process may be waited for again after this call completes. +.El +.sp +For the +.Fn waitid +and +.Fn wait6 +functions, at least one of the options +.Dv WEXITED , +.Dv WUNTRACED , +.Dv WSTOPPED , +.Dv WTRAPPED , +or +.Dv WCONTINUED +must be specified. +Otherwise there will be no events for the call to report. +To avoid hanging indefinitely in such a case these functions +return -1 with +.Dv errno +set to +.Dv EINVAL . +.Pp +If +.Fa rusage +is non-NULL, a summary of the resources used by the terminated +process and all its children is returned. +.Pp +If +.Fa wrusage +is non-NULL, separate summaries are returned for the resources used +by the terminated process and the resources used by all its children. +.Pp +If +.Fa infop +is non-NULL, a +.Dv siginfo_t +structure is returned with the +.Fa si_signo +field set to +.Dv SIGCHLD +and the +.Fa si_pid +field set to the process ID of the process reporting status. +For the exited process, the +.Fa si_status +field of the +.Dv siginfo_t +structure contains the full 32 bit exit status passed to +.Xr _exit 2 ; +the +.Fa status +argument of other calls only returns 8 lowest bits of the exit status. +.Pp +When the +.Dv WNOHANG +option is specified and no processes +wish to report status, +.Fn waitid +sets the +.Fa si_signo +and +.Fa si_pid +fields in +.Fa infop +to zero. +Checking these fields is the only way to know if a status change was reported. +.Pp +When the +.Dv WNOHANG +option is specified and no processes +wish to report status, +.Fn wait4 +and +.Fn wait6 +return a +process id +of 0. +.Pp +The +.Fn wait +call is the same as +.Fn wait4 +with a +.Fa wpid +value of -1, +with an +.Fa options +value of zero, +and a +.Fa rusage +value of +.Dv NULL . +The +.Fn waitpid +function is identical to +.Fn wait4 +with an +.Fa rusage +value of +.Dv NULL . +The older +.Fn wait3 +call is the same as +.Fn wait4 +with a +.Fa wpid +value of -1. +The +.Fn wait4 +function is identical to +.Fn wait6 +with the flags +.Dv WEXITED +and +.Dv WTRAPPED +set in +.Fa options +and +.Fa infop +set to +.Dv NULL . +.Pp +The following macros may be used to test the current status of the process. +Exactly one of the following four macros will evaluate to a non-zero +.Pq true +value: +.Bl -tag -width Ds +.It Fn WIFCONTINUED status +True if the process has not terminated, and +has continued after a job control stop or detach of a debugger. +This macro can be true only if the wait call specified the +.Dv WCONTINUED +option. +.It Fn WIFEXITED status +True if the process terminated normally by a call to +.Xr _exit 2 +or +.Xr exit 3 . +.It Fn WIFSIGNALED status +True if the process terminated due to receipt of a signal. +.It Fn WIFSTOPPED status +True if the process has not terminated, but has stopped and can be restarted. +This macro can be true only if the wait call specified the +.Dv WUNTRACED +option +or if the child process is being traced (see +.Xr ptrace 2 ) . +.El +.Pp +Depending on the values of those macros, the following macros +produce the remaining status information about the child process: +.Bl -tag -width Ds +.It Fn WEXITSTATUS status +If +.Fn WIFEXITED status +is true, evaluates to the low-order 8 bits +of the argument passed to +.Xr _exit 2 +or +.Xr exit 3 +by the child. +.It Fn WTERMSIG status +If +.Fn WIFSIGNALED status +is true, evaluates to the number of the signal +that caused the termination of the process. +.It Fn WCOREDUMP status +If +.Fn WIFSIGNALED status +is true, evaluates as true if the termination +of the process was accompanied by the creation of a core file +containing an image of the process when the signal was received. +.It Fn WSTOPSIG status +If +.Fn WIFSTOPPED status +is true, evaluates to the number of the signal +that caused the process to stop. +.El +.Sh NOTES +See +.Xr sigaction 2 +for a list of termination signals. +A status of 0 indicates normal termination. +.Pp +If a parent process terminates without +waiting for all of its child processes to terminate, +the remaining child processes are re-assigned to the reaper +of the exiting process as the parent, see +.Xr procctl 2 +.Dv PROC_REAP_ACQUIRE . +If no specific reaper was assigned, the process with ID 1, the init process, +becomes the parent of the orphaned children by default. +.Pp +If a signal is caught while any of the +.Fn wait +calls are pending, +the call may be interrupted or restarted when the signal-catching routine +returns, +depending on the options in effect for the signal; +see discussion of +.Dv SA_RESTART +in +.Xr sigaction 2 . +.Pp +The implementation queues one +.Dv SIGCHLD +signal for each child process whose +status has changed; if +.Fn wait +returns because the status of a child process is available, the pending +SIGCHLD signal associated with the process ID of the child process will +be discarded. +Any other pending +.Dv SIGCHLD +signals remain pending. +.Pp +If +.Dv SIGCHLD +is blocked and +.Fn wait +returns because the status of a child process is available, the pending +.Dv SIGCHLD +signal will be cleared unless another status of the child process +is available. +.Sh RETURN VALUES +If +.Fn wait +returns due to a stopped, continued, +or terminated child process, the process ID of the child +is returned to the calling process. +Otherwise, a value of \-1 +is returned and +.Va errno +is set to indicate the error. +.Pp +If +.Fn wait6 , +.Fn wait4 , +.Fn wait3 , +or +.Fn waitpid +returns due to a stopped, continued, +or terminated child process, the process ID of the child +is returned to the calling process. +If there are no children not previously awaited, +-1 is returned with +.Va errno +set to +.Er ECHILD . +Otherwise, if +.Dv WNOHANG +is specified and there are +no stopped, continued or exited children, +0 is returned. +If an error is detected or a caught signal aborts the call, +a value of -1 +is returned and +.Va errno +is set to indicate the error. +.Pp +If +.Fn waitid +returns because one or more processes have a state change to report, +0 is returned. +If an error is detected, +a value of -1 +is returned and +.Va errno +is set to indicate the error. +If +.Dv WNOHANG +is specified and there are +no stopped, continued or exited children, +0 is returned. +The +.Fa si_signo +and +.Fa si_pid +fields of +.Fa infop +must be checked against zero to determine if a process reported status. +.Pp +The +.Fn wait +family of functions will only return a child process created with +.Xr pdfork 2 +if the calling process is not in +.Xr capsicum 4 +capability mode, and +.Nm +has been explicitly given the child's process ID. +.Sh ERRORS +The +.Fn wait +function +will fail and return immediately if: +.Bl -tag -width Er +.It Bq Er ECHILD +The calling process has no existing unwaited-for +child processes. +.It Bq Er ECHILD +No status from the terminated child process is available +because the calling process has asked the system to discard +such status by ignoring the signal +.Dv SIGCHLD +or setting the flag +.Dv SA_NOCLDWAIT +for that signal. +.It Bq Er EFAULT +The +.Fa status +or +.Fa rusage +argument points to an illegal address. +(May not be detected before exit of a child process.) +.It Bq Er EINTR +The call was interrupted by a caught signal, +or the signal did not have the +.Dv SA_RESTART +flag set. +.It Bq Er EINVAL +An invalid value was specified for +.Fa options , +or +.Fa idtype +and +.Fa id +do not specify a valid set of processes. +.El +.Sh SEE ALSO +.Xr _exit 2 , +.Xr procctl 2 , +.Xr ptrace 2 , +.Xr sigaction 2 , +.Xr exit 3 , +.Xr siginfo 3 +.Sh STANDARDS +The +.Fn wait , +.Fn waitpid , +and +.Fn waitid +functions are defined by POSIX; +.Fn wait6 , +.Fn wait4 , +and +.Fn wait3 +are not specified by POSIX. +The +.Fn WCOREDUMP +macro +is an extension to the POSIX interface. +.Pp +The ability to use the +.Dv WNOWAIT +flag with +.Fn waitpid +is an extension; +.Tn POSIX +only permits this flag with +.Fn waitid . +.Sh HISTORY +The +.Fn wait +function appeared in +.At v1 . diff --git a/lib/libsys/write.2 b/lib/libsys/write.2 new file mode 100644 index 000000000000..d2ff41ceead9 --- /dev/null +++ b/lib/libsys/write.2 @@ -0,0 +1,307 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd February 11, 2021 +.Dt WRITE 2 +.Os +.Sh NAME +.Nm write , +.Nm writev , +.Nm pwrite , +.Nm pwritev +.Nd write output +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft ssize_t +.Fn write "int fd" "const void *buf" "size_t nbytes" +.Ft ssize_t +.Fn pwrite "int fd" "const void *buf" "size_t nbytes" "off_t offset" +.In sys/uio.h +.Ft ssize_t +.Fn writev "int fd" "const struct iovec *iov" "int iovcnt" +.Ft ssize_t +.Fn pwritev "int fd" "const struct iovec *iov" "int iovcnt" "off_t offset" +.Sh DESCRIPTION +The +.Fn write +system call +attempts to write +.Fa nbytes +of data to the object referenced by the descriptor +.Fa fd +from the buffer pointed to by +.Fa buf . +The +.Fn writev +system call +performs the same action, but gathers the output data +from the +.Fa iovcnt +buffers specified by the members of the +.Fa iov +array: iov[0], iov[1], ..., iov[iovcnt\|-\|1]. +The +.Fn pwrite +and +.Fn pwritev +system calls +perform the same functions, but write to the specified position in +the file without modifying the file pointer. +.Pp +For +.Fn writev +and +.Fn pwritev , +the +.Fa iovec +structure is defined as: +.Pp +.Bd -literal -offset indent -compact +struct iovec { + void *iov_base; /* Base address. */ + size_t iov_len; /* Length. */ +}; +.Ed +.Pp +Each +.Fa iovec +entry specifies the base address and length of an area +in memory from which data should be written. +The +.Fn writev +system call +will always write a complete area before proceeding +to the next. +.Pp +On objects capable of seeking, the +.Fn write +starts at a position +given by the pointer associated with +.Fa fd , +see +.Xr lseek 2 . +Upon return from +.Fn write , +the pointer is incremented by the number of bytes which were written. +.Pp +Objects that are not capable of seeking always write from the current +position. +The value of the pointer associated with such an object +is undefined. +.Pp +If the real user is not the super-user, then +.Fn write +clears the set-user-id bit on a file. +This prevents penetration of system security +by a user who +.Dq captures +a writable set-user-id file +owned by the super-user. +.Pp +When using non-blocking I/O on objects such as sockets that are subject +to flow control, +.Fn write +and +.Fn writev +may write fewer bytes than requested; +the return value must be noted, +and the remainder of the operation should be retried when possible. +.Sh RETURN VALUES +Upon successful completion the number of bytes which were written +is returned. +Otherwise a -1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn write , +.Fn writev , +.Fn pwrite +and +.Fn pwritev +system calls +will fail and the file pointer will remain unchanged if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument +is not a valid descriptor open for writing. +.It Bq Er EPIPE +An attempt is made to write to a pipe that is not open +for reading by any process. +.It Bq Er EPIPE +An attempt is made to write to a socket of type +.Dv SOCK_STREAM +that is not connected to a peer socket. +.It Bq Er EFBIG +An attempt was made to write a file that exceeds the process's +file size limit or the maximum file size. +.It Bq Er EFAULT +Part of +.Fa iov +or data to be written to the file +points outside the process's allocated address space. +.It Bq Er EINVAL +The pointer associated with +.Fa fd +was negative. +.It Bq Er ENOSPC +There is no free space remaining on the file system +containing the file. +.It Bq Er EDQUOT +The user's quota of disk blocks on the file system +containing the file has been exhausted. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.It Bq Er EINTR +A signal interrupted the write before it could be completed. +.It Bq Er EAGAIN +The file was marked for non-blocking I/O, +and no data could be written immediately. +.It Bq Er EINVAL +The value +.Fa nbytes +is greater than +.Dv SSIZE_MAX +(or greater than +.Dv INT_MAX , +if the sysctl +.Va debug.iosize_max_clamp +is non-zero). +.It Bq Er EINVAL +The file descriptor refers to a raw device, and the write +offset or size is not a multiple of the device's block size. +.It Bq Er EINTEGRITY +The backing store for +.Fa fd +detected corrupted data while reading. +(For example, writing a partial filesystem block may require first reading +the existing block which may trigger this error.) +.El +.Pp +In addition, +.Fn writev +and +.Fn pwritev +may return one of the following errors: +.Bl -tag -width Er +.It Bq Er EDESTADDRREQ +The destination is no longer available when writing to a +.Ux +domain datagram socket on which +.Xr connect 2 +had been used to set a destination address. +.It Bq Er EINVAL +The +.Fa iovcnt +argument +was less than or equal to 0, or greater than +.Dv IOV_MAX . +.It Bq Er EINVAL +One of the +.Fa iov_len +values in the +.Fa iov +array was negative. +.It Bq Er EINVAL +The sum of the +.Fa iov_len +values is greater than +.Dv SSIZE_MAX +(or greater than +.Dv INT_MAX , +if the sysctl +.Va debug.iosize_max_clamp +is non-zero). +.It Bq Er ENOBUFS +The mbuf pool has been completely exhausted when writing to a socket. +.El +.Pp +The +.Fn pwrite +and +.Fn pwritev +system calls may also return the following errors: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa offset +value was negative. +.It Bq Er ESPIPE +The file descriptor is associated with a pipe, socket, or FIFO. +.El +.Sh SEE ALSO +.Xr fcntl 2 , +.Xr lseek 2 , +.Xr open 2 , +.Xr pipe 2 , +.Xr select 2 +.Sh STANDARDS +The +.Fn write +system call is expected to conform to +.St -p1003.1-90 . +The +.Fn writev +and +.Fn pwrite +system calls are expected to conform to +.St -xpg4.2 . +.Sh HISTORY +The +.Fn pwritev +system call appeared in +.Fx 6.0 . +The +.Fn pwrite +function appeared in +.At V.4 . +The +.Fn writev +system call appeared in +.Bx 4.2 . +The +.Fn write +function appeared in +.At v1 . +.Sh BUGS +The +.Fn pwrite +system call appends the file without changing the file offset if +.Dv O_APPEND +is set, contrary to +.St -p1003.1-2008 +where +.Fn pwrite +writes into +.Fa offset +regardless of whether +.Dv O_APPEND +is set. diff --git a/lib/libsys/x86/Makefile.sys b/lib/libsys/x86/Makefile.sys new file mode 100644 index 000000000000..483d1784bdc9 --- /dev/null +++ b/lib/libsys/x86/Makefile.sys @@ -0,0 +1,24 @@ +.PATH: ${LIBSYS_SRCTOP}/x86 + +SRCS+= \ + __vdso_gettc.c \ + pkru.c \ + sched_getcpu_x86.c + +.if ${LIB} == "sys" +MAN+= \ + pkru.3 +.endif # ${LIB} == "sys" + +# Note: vdso support for hyperv only on amd64 +.if ${MACHINE_CPUARCH} == "amd64" && ${MK_HYPERV} != "no" +CFLAGS+= -DWANT_HYPERV +.endif +# We can't use sanitizer instrumentation on ifuncs called during sanitizer +# runtime startup. +.if ${MK_ASAN} != "no" +CFLAGS.__vdso_gettc.c+=-fno-sanitize=address +.endif +.if ${MK_UBSAN} != "no" +CFLAGS.__vdso_gettc.c+=-fno-sanitize=undefined +.endif diff --git a/lib/libsys/x86/__vdso_gettc.c b/lib/libsys/x86/__vdso_gettc.c new file mode 100644 index 000000000000..ea05f5abf62a --- /dev/null +++ b/lib/libsys/x86/__vdso_gettc.c @@ -0,0 +1,453 @@ +/*- + * Copyright (c) 2012 Konstantin Belousov <kib@FreeBSD.org> + * Copyright (c) 2016, 2017, 2019 The FreeBSD Foundation + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * 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. + */ + +#include <sys/param.h> +#include "namespace.h" +#include <sys/capsicum.h> +#include <sys/elf.h> +#include <sys/fcntl.h> +#include <sys/mman.h> +#include <sys/time.h> +#include <sys/vdso.h> +#include <errno.h> +#include <string.h> +#include <unistd.h> +#include "un-namespace.h" +#include <machine/atomic.h> +#include <machine/cpufunc.h> +#include <machine/pvclock.h> +#include <machine/specialreg.h> +#include <dev/acpica/acpi_hpet.h> +#ifdef WANT_HYPERV +#include <dev/hyperv/hyperv.h> +#endif +#include <x86/ifunc.h> +#include "libc_private.h" + +static inline u_int +rdtsc_low(const struct vdso_timehands *th) +{ + u_int rv; + + __asm __volatile("rdtsc; shrd %%cl, %%edx, %0" + : "=a" (rv) : "c" (th->th_x86_shift) : "edx"); + return (rv); +} + +static inline u_int +rdtscp_low(const struct vdso_timehands *th) +{ + u_int rv; + + __asm __volatile("rdtscp; movl %%edi,%%ecx; shrd %%cl, %%edx, %0" + : "=a" (rv) : "D" (th->th_x86_shift) : "ecx", "edx"); + return (rv); +} + +static u_int +rdtsc_low_mb_lfence(const struct vdso_timehands *th) +{ + lfence(); + return (rdtsc_low(th)); +} + +static u_int +rdtsc_low_mb_mfence(const struct vdso_timehands *th) +{ + mfence(); + return (rdtsc_low(th)); +} + +static u_int +rdtsc_low_mb_none(const struct vdso_timehands *th) +{ + return (rdtsc_low(th)); +} + +static u_int +rdtsc32_mb_lfence(void) +{ + lfence(); + return (rdtsc32()); +} + +static uint64_t +rdtsc_mb_lfence(void) +{ + lfence(); + return (rdtsc()); +} + +static u_int +rdtsc32_mb_mfence(void) +{ + mfence(); + return (rdtsc32()); +} + +static uint64_t +rdtsc_mb_mfence(void) +{ + mfence(); + return (rdtsc()); +} + +static u_int +rdtsc32_mb_none(void) +{ + return (rdtsc32()); +} + +static uint64_t +rdtsc_mb_none(void) +{ + return (rdtsc()); +} + +static u_int +rdtscp32_(void) +{ + return (rdtscp32()); +} + +static uint64_t +rdtscp_(void) +{ + return (rdtscp()); +} + +struct tsc_selector_tag { + u_int (*ts_rdtsc32)(void); + uint64_t (*ts_rdtsc)(void); + u_int (*ts_rdtsc_low)(const struct vdso_timehands *); +}; + +static const struct tsc_selector_tag tsc_selector[] = { + [0] = { /* Intel, LFENCE */ + .ts_rdtsc32 = rdtsc32_mb_lfence, + .ts_rdtsc = rdtsc_mb_lfence, + .ts_rdtsc_low = rdtsc_low_mb_lfence, + }, + [1] = { /* AMD, MFENCE */ + .ts_rdtsc32 = rdtsc32_mb_mfence, + .ts_rdtsc = rdtsc_mb_mfence, + .ts_rdtsc_low = rdtsc_low_mb_mfence, + }, + [2] = { /* No SSE2 */ + .ts_rdtsc32 = rdtsc32_mb_none, + .ts_rdtsc = rdtsc_mb_none, + .ts_rdtsc_low = rdtsc_low_mb_none, + }, + [3] = { /* RDTSCP */ + .ts_rdtsc32 = rdtscp32_, + .ts_rdtsc = rdtscp_, + .ts_rdtsc_low = rdtscp_low, + }, +}; + +static int +tsc_selector_idx(u_int cpu_feature) +{ + u_int amd_feature, cpu_exthigh, p[4], v[3]; + static const char amd_id[] = "AuthenticAMD"; + static const char hygon_id[] = "HygonGenuine"; + bool amd_cpu; + + if (cpu_feature == 0) + return (2); /* should not happen due to RDTSC */ + + do_cpuid(0, p); + v[0] = p[1]; + v[1] = p[3]; + v[2] = p[2]; + amd_cpu = memcmp(v, amd_id, sizeof(amd_id) - 1) == 0 || + memcmp(v, hygon_id, sizeof(hygon_id) - 1) == 0; + + if (cpu_feature != 0) { + do_cpuid(0x80000000, p); + cpu_exthigh = p[0]; + } else { + cpu_exthigh = 0; + } + if (cpu_exthigh >= 0x80000001) { + do_cpuid(0x80000001, p); + amd_feature = p[3]; + } else { + amd_feature = 0; + } + + if ((amd_feature & AMDID_RDTSCP) != 0) + return (3); + if ((cpu_feature & CPUID_SSE2) == 0) + return (2); + return (amd_cpu ? 1 : 0); +} + +DEFINE_UIFUNC(static, u_int, __vdso_gettc_rdtsc_low, + (const struct vdso_timehands *th)) +{ + return (tsc_selector[tsc_selector_idx(cpu_feature)].ts_rdtsc_low); +} + +DEFINE_UIFUNC(static, u_int, __vdso_gettc_rdtsc32, (void)) +{ + return (tsc_selector[tsc_selector_idx(cpu_feature)].ts_rdtsc32); +} + +DEFINE_UIFUNC(static, uint64_t, __vdso_gettc_rdtsc, (void)) +{ + return (tsc_selector[tsc_selector_idx(cpu_feature)].ts_rdtsc); +} + +#define HPET_DEV_MAP_MAX 10 +static volatile char *hpet_dev_map[HPET_DEV_MAP_MAX]; + +static void +__vdso_init_hpet(uint32_t u) +{ + static const char devprefix[] = "/dev/hpet"; + char devname[64], *c, *c1, t; + volatile char *new_map, *old_map; + unsigned int mode; + uint32_t u1; + int fd; + + c1 = c = stpcpy(devname, devprefix); + u1 = u; + do { + *c++ = u1 % 10 + '0'; + u1 /= 10; + } while (u1 != 0); + *c = '\0'; + for (c--; c1 != c; c1++, c--) { + t = *c1; + *c1 = *c; + *c = t; + } + + old_map = hpet_dev_map[u]; + if (old_map != NULL) + return; + + /* + * Explicitely check for the capability mode to avoid + * triggering trap_enocap on the device open by absolute path. + */ + if ((cap_getmode(&mode) == 0 && mode != 0) || + (fd = _open(devname, O_RDONLY | O_CLOEXEC)) == -1) { + /* Prevent the caller from re-entering. */ + atomic_cmpset_rel_ptr((volatile uintptr_t *)&hpet_dev_map[u], + (uintptr_t)old_map, (uintptr_t)MAP_FAILED); + return; + } + + new_map = mmap(NULL, PAGE_SIZE, PROT_READ, MAP_SHARED, fd, 0); + _close(fd); + if (atomic_cmpset_rel_ptr((volatile uintptr_t *)&hpet_dev_map[u], + (uintptr_t)old_map, (uintptr_t)new_map) == 0 && + new_map != MAP_FAILED) + munmap((void *)new_map, PAGE_SIZE); +} + +#ifdef WANT_HYPERV + +#define HYPERV_REFTSC_DEVPATH "/dev/" HYPERV_REFTSC_DEVNAME + +/* + * NOTE: + * We use 'NULL' for this variable to indicate that initialization + * is required. And if this variable is 'MAP_FAILED', then Hyper-V + * reference TSC can not be used, e.g. in misconfigured jail. + */ +static struct hyperv_reftsc *hyperv_ref_tsc; + +static void +__vdso_init_hyperv_tsc(void) +{ + int fd; + unsigned int mode; + + if (cap_getmode(&mode) == 0 && mode != 0) + goto fail; + + fd = _open(HYPERV_REFTSC_DEVPATH, O_RDONLY | O_CLOEXEC); + if (fd < 0) + goto fail; + hyperv_ref_tsc = mmap(NULL, sizeof(*hyperv_ref_tsc), PROT_READ, + MAP_SHARED, fd, 0); + _close(fd); + + return; +fail: + /* Prevent the caller from re-entering. */ + hyperv_ref_tsc = MAP_FAILED; +} + +static int +__vdso_hyperv_tsc(struct hyperv_reftsc *tsc_ref, u_int *tc) +{ + uint64_t disc, ret, tsc, scale; + uint32_t seq; + int64_t ofs; + + while ((seq = atomic_load_acq_int(&tsc_ref->tsc_seq)) != 0) { + scale = tsc_ref->tsc_scale; + ofs = tsc_ref->tsc_ofs; + + mfence(); /* XXXKIB */ + tsc = rdtsc(); + + /* ret = ((tsc * scale) >> 64) + ofs */ + __asm__ __volatile__ ("mulq %3" : + "=d" (ret), "=a" (disc) : + "a" (tsc), "r" (scale)); + ret += ofs; + + atomic_thread_fence_acq(); + if (tsc_ref->tsc_seq == seq) { + *tc = ret; + return (0); + } + + /* Sequence changed; re-sync. */ + } + return (ENOSYS); +} + +#endif /* WANT_HYPERV */ + +static struct pvclock_vcpu_time_info *pvclock_timeinfos; + +static int +__vdso_pvclock_gettc(const struct vdso_timehands *th, u_int *tc) +{ + uint64_t delta, ns, tsc; + struct pvclock_vcpu_time_info *ti; + uint32_t cpuid_ti, cpuid_tsc, version; + bool stable; + + do { + ti = &pvclock_timeinfos[0]; + version = atomic_load_acq_32(&ti->version); + stable = (ti->flags & th->th_x86_pvc_stable_mask) != 0; + if (stable) { + tsc = __vdso_gettc_rdtsc(); + } else { + (void)rdtscp_aux(&cpuid_ti); + ti = &pvclock_timeinfos[cpuid_ti]; + version = atomic_load_acq_32(&ti->version); + tsc = rdtscp_aux(&cpuid_tsc); + } + delta = tsc - ti->tsc_timestamp; + ns = ti->system_time + pvclock_scale_delta(delta, + ti->tsc_to_system_mul, ti->tsc_shift); + atomic_thread_fence_acq(); + } while ((ti->version & 1) != 0 || ti->version != version || + (!stable && cpuid_ti != cpuid_tsc)); + *tc = MAX(ns, th->th_x86_pvc_last_systime); + return (0); +} + +static void +__vdso_init_pvclock_timeinfos(void) +{ + struct pvclock_vcpu_time_info *timeinfos; + size_t len; + int fd, ncpus; + unsigned int mode; + + timeinfos = MAP_FAILED; + if (_elf_aux_info(AT_NCPUS, &ncpus, sizeof(ncpus)) != 0 || + (cap_getmode(&mode) == 0 && mode != 0) || + (fd = _open("/dev/" PVCLOCK_CDEVNAME, O_RDONLY | O_CLOEXEC)) < 0) + goto leave; + len = ncpus * sizeof(*pvclock_timeinfos); + timeinfos = mmap(NULL, len, PROT_READ, MAP_SHARED, fd, 0); + _close(fd); +leave: + if (atomic_cmpset_rel_ptr( + (volatile uintptr_t *)&pvclock_timeinfos, (uintptr_t)NULL, + (uintptr_t)timeinfos) == 0 && timeinfos != MAP_FAILED) + (void)munmap((void *)timeinfos, len); +} + +#pragma weak __vdso_gettc +int +__vdso_gettc(const struct vdso_timehands *th, u_int *tc) +{ + volatile char *map; + uint32_t idx; + + switch (th->th_algo) { + case VDSO_TH_ALGO_X86_TSC: + *tc = th->th_x86_shift > 0 ? __vdso_gettc_rdtsc_low(th) : + __vdso_gettc_rdtsc32(); + return (0); + case VDSO_TH_ALGO_X86_HPET: + idx = th->th_x86_hpet_idx; + if (idx >= HPET_DEV_MAP_MAX) + return (ENOSYS); + map = (volatile char *)atomic_load_acq_ptr( + (volatile uintptr_t *)&hpet_dev_map[idx]); + if (map == NULL) { + __vdso_init_hpet(idx); + map = (volatile char *)atomic_load_acq_ptr( + (volatile uintptr_t *)&hpet_dev_map[idx]); + } + if (map == MAP_FAILED) + return (ENOSYS); + *tc = *(volatile uint32_t *)(map + HPET_MAIN_COUNTER); + return (0); +#ifdef WANT_HYPERV + case VDSO_TH_ALGO_X86_HVTSC: + if (hyperv_ref_tsc == NULL) + __vdso_init_hyperv_tsc(); + if (hyperv_ref_tsc == MAP_FAILED) + return (ENOSYS); + return (__vdso_hyperv_tsc(hyperv_ref_tsc, tc)); +#endif + case VDSO_TH_ALGO_X86_PVCLK: + if (pvclock_timeinfos == NULL) + __vdso_init_pvclock_timeinfos(); + if (pvclock_timeinfos == MAP_FAILED) + return (ENOSYS); + return (__vdso_pvclock_gettc(th, tc)); + default: + return (ENOSYS); + } +} + +#pragma weak __vdso_gettimekeep +int +__vdso_gettimekeep(struct vdso_timekeep **tk) +{ + + return (_elf_aux_info(AT_TIMEKEEP, tk, sizeof(*tk))); +} diff --git a/lib/libsys/x86/pkru.3 b/lib/libsys/x86/pkru.3 new file mode 100644 index 000000000000..95bc66c979ac --- /dev/null +++ b/lib/libsys/x86/pkru.3 @@ -0,0 +1,203 @@ +.\" Copyright (c) 2019 The FreeBSD Foundation +.\" +.\" This documentation was written by +.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" 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 AUTHORS 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 AUTHORS 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. +.\" +.Dd February 16, 2019 +.Dt PKRU 3 +.Os +.Sh NAME +.Nm Protection Key Rights for User pages +.Nd provide fast user-managed key-based access control for pages +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In machine/sysarch.h +.Ft int +.Fn x86_pkru_get_perm "unsigned int keyidx" "int *access" "int *modify" +.Ft int +.Fn x86_pkru_set_perm "unsigned int keyidx" "int access" "int modify" +.Ft int +.Fo x86_pkru_protect_range +.Fa "void *addr" +.Fa "unsigned long len" +.Fa "unsigned int keyidx" +.Fa "int flag" +.Fc +.Ft int +.Fn x86_pkru_unprotect_range "void *addr" "unsigned long len" +.Sh DESCRIPTION +The protection keys feature provides an additional mechanism, besides the +normal page permissions as established by +.Xr mmap 2 +and +.Xr mprotect 2 , +to control access to user-mode addresses. +The mechanism gives safety measures which can be used to avoid +incidental read or modification of sensitive memory, +or as a debugging feature. +It cannot guard against conscious accesses since permissions +are user-controllable. +.Pp +If supported by hardware, each mapped user linear address +has an associated 4-bit protection key. +A new per-thread PKRU hardware register determines, for each protection +key, whether user-mode addresses with that protection key may be +read or written. +.Pp +Only one key may apply to a given range at a time. +The default protection key index is zero, it is used even if no key +was explicitly assigned to the address, or if the key was removed. +.Pp +The protection prevents the system from accessing user addresses as well +as the user applications. +When a system call was unable to read or write user memory due to key +protection, it returns the +.Er EFAULT +error code. +Note that some side effects may have occurred if this error is reported. +.Pp +Protection keys require that the system uses 4-level paging +(also called long mode), +which means that it is only available on amd64 system. +Both 64-bit and 32-bit applications can use protection keys. +More information about the hardware feature is provided in the IA32 Software +Developer's Manual published by Intel Corp. +.Pp +The key indexes written into the page table entries are managed by the +.Fn sysarch +syscall. +Per-key permissions are managed using the user-mode instructions +.Em RDPKRU +and +.Em WRPKRU . +The system provides convenient library helpers for both the syscall and +the instructions, described below. +.Pp +The +.Fn x86_pkru_protect_range +function assigns key +.Fa keyidx +to the range starting at +.Fa addr +and having length +.Fa len . +Starting address is truncated to the page start, +and the end is rounded up to the end of the page. +After a successful call, the range has the specified key assigned, +even if the key is zero and it did not change the page table entries. +.Pp +The +.Fa flags +argument takes the logical OR of the following values: +.Bl -tag -width +.It Bq Va AMD64_PKRU_EXCL +Only assign the key if the range does not have any other keys assigned +(including the zero key). +You must first remove any existing key with +.Fn x86_pkru_unprotect_range +in order for this request to succeed. +If the +.Va AMD64_PKRU_EXCL +flag is not specified, +.Fn x86_pkru_protect_range +replaces any existing key. +.It Bq Va AMD64_PKRU_PERSIST +The keys assigned to the range are persistent. +They are re-established when the current mapping is destroyed +and a new mapping is created in any sub-range of the specified range. +You must use a +.Fn x86_pkru_unprotect_range +call to forget the key. +.El +.Pp +The +.Fn x86_pkru_unprotect_range +function removes any keys assigned to the specified range. +Existing mappings are changed to use key index zero in page table entries. +Keys are no longer considered installed for all mappings in the range, +for the purposes of +.Fn x86_pkru_protect_range +with the +.Va AMD64_PKRU_EXCL +flag. +.Pp +The +.Fn x86_pkru_get_perm +function returns access rights for the key specified by the +.Fa keyidx +argument. +If the value pointed to by +.Fa access +is zero after the call, no read or write permissions is granted for +mappings which are assigned the key +.Fa keyidx . +If +.Fa access +is not zero, read access is permitted. +The non-zero value of the variable pointed to by the +.Fa modify +argument indicates that write access is permitted. +.Pp +Conversely, the +.Fn x86_pkru_set_perm +establishes the access and modify permissions for the given key index +as specified by its arguments. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EOPNOTSUPP +The hardware does not support protection keys. +.It Bq Er EINVAL +The supplied key index is invalid (greater than 15). +.It Bq Er EINVAL +The supplied +.Fa flags +argument for +.Fn x86_pkru_protect_range +has reserved bits set. +.It Bq Er EFAULT +The supplied address range does not completely fit into the user-managed +address range. +.It Bq Er ENOMEM +The memory shortage prevents the completion of the operation. +.It Bq Er EBUSY +The +.Va AMD64_PKRU_EXCL +flag was specified for +.Fn x86_pkru_protect_range +and the range already has defined protection keys. +.El +.Sh SEE ALSO +.Xr mmap 2 , +.Xr mprotect 2 , +.Xr munmap 2 , +.Xr sysarch 2 +.Sh STANDARDS +The +.Nm +functions are non-standard and first appeared in +.Fx 13.0 . diff --git a/lib/libsys/x86/pkru.c b/lib/libsys/x86/pkru.c new file mode 100644 index 000000000000..b6ae181c131f --- /dev/null +++ b/lib/libsys/x86/pkru.c @@ -0,0 +1,134 @@ +/*- + * Copyright (c) 2019 The FreeBSD Foundation + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * 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. + */ + +#include <sys/param.h> +#include <machine/cpufunc.h> +#include <machine/specialreg.h> +#include <machine/sysarch.h> +#include <x86/ifunc.h> +#include <errno.h> +#include <string.h> + +#define MAX_PKRU_IDX 0xf +#ifdef __i386__ +#define X86_SET_PKRU I386_SET_PKRU +#define X86_CLEAR_PKRU I386_CLEAR_PKRU +#else +#define X86_SET_PKRU AMD64_SET_PKRU +#define X86_CLEAR_PKRU AMD64_CLEAR_PKRU +#endif + +static int +x86_pkru_get_perm_unsup(u_int keyidx, int *access, int *modify) +{ + + errno = EOPNOTSUPP; + return (-1); +} + +static int +x86_pkru_get_perm_hw(u_int keyidx, int *access, int *modify) +{ + uint32_t pkru; + + if (keyidx > MAX_PKRU_IDX) { + errno = EINVAL; + return (-1); + } + keyidx *= 2; + pkru = rdpkru(); + *access = (pkru & (1 << keyidx)) == 0; + *modify = (pkru & (2 << keyidx)) == 0; + return (0); +} + +DEFINE_UIFUNC(, int, x86_pkru_get_perm, (u_int, int *, int *)) +{ + + return ((cpu_stdext_feature2 & CPUID_STDEXT2_OSPKE) == 0 ? + x86_pkru_get_perm_unsup : x86_pkru_get_perm_hw); +} + +static int +x86_pkru_set_perm_unsup(u_int keyidx, int access, int modify) +{ + + errno = EOPNOTSUPP; + return (-1); +} + +static int +x86_pkru_set_perm_hw(u_int keyidx, int access, int modify) +{ + uint32_t pkru; + + if (keyidx > MAX_PKRU_IDX) { + errno = EINVAL; + return (-1); + } + keyidx *= 2; + pkru = rdpkru(); + pkru &= ~(3 << keyidx); + if (!access) + pkru |= 1 << keyidx; + if (!modify) + pkru |= 2 << keyidx; + wrpkru(pkru); + return (0); +} + +DEFINE_UIFUNC(, int, x86_pkru_set_perm, (u_int, int, int)) +{ + + return ((cpu_stdext_feature2 & CPUID_STDEXT2_OSPKE) == 0 ? + x86_pkru_set_perm_unsup : x86_pkru_set_perm_hw); +} + +int +x86_pkru_protect_range(void *addr, unsigned long len, u_int keyidx, int flags) +{ + struct amd64_set_pkru a64pkru; + + memset(&a64pkru, 0, sizeof(a64pkru)); + a64pkru.addr = addr; + a64pkru.len = len; + a64pkru.keyidx = keyidx; + a64pkru.flags = flags; + return (sysarch(X86_SET_PKRU, &a64pkru)); +} + +int +x86_pkru_unprotect_range(void *addr, unsigned long len) +{ + struct amd64_set_pkru a64pkru; + + memset(&a64pkru, 0, sizeof(a64pkru)); + a64pkru.addr = addr; + a64pkru.len = len; + return (sysarch(X86_CLEAR_PKRU, &a64pkru)); +} diff --git a/lib/libsys/x86/sched_getcpu_x86.c b/lib/libsys/x86/sched_getcpu_x86.c new file mode 100644 index 000000000000..13ba18ef5e36 --- /dev/null +++ b/lib/libsys/x86/sched_getcpu_x86.c @@ -0,0 +1,81 @@ +/*- + * Copyright (c) 2021 The FreeBSD Foundation + * + * This software were developed by Konstantin Belousov <kib@FreeBSD.org> + * under sponsorship from the FreeBSD Foundation. + * + * 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. + */ + +#include <sys/param.h> +#include <machine/cpufunc.h> +#include <machine/specialreg.h> +#include <machine/sysarch.h> +#include <x86/ifunc.h> +#include <errno.h> +#include <sched.h> +#include "libc_private.h" + +static int +sched_getcpu_sys(void) +{ + return (__sys_sched_getcpu()); +} + +static int +sched_getcpu_rdpid(void) +{ + register_t res; + + __asm("rdpid %0" : "=r" (res)); + return ((int)res); +} + +static int +sched_getcpu_rdtscp(void) +{ + int res; + + __asm("rdtscp" : "=c" (res) : : "eax", "edx"); + return (res); +} + +DEFINE_UIFUNC(, int, sched_getcpu, (void)) +{ + u_int amd_feature, cpu_exthigh, p[4]; + + if ((cpu_stdext_feature2 & CPUID_STDEXT2_RDPID) != 0) + return (sched_getcpu_rdpid); + + amd_feature = 0; + if (cpu_feature != 0) { + do_cpuid(0x80000000, p); + cpu_exthigh = p[0]; + if (cpu_exthigh >= 0x80000001) { + do_cpuid(0x80000001, p); + amd_feature = p[3]; + } + } + + return ((amd_feature & AMDID_RDTSCP) == 0 ? + sched_getcpu_sys : sched_getcpu_rdtscp); +} |