diff options
Diffstat (limited to 'lib/libc/sys')
| -rw-r--r-- | lib/libc/sys/Makefile.inc | 110 | ||||
| -rw-r--r-- | lib/libc/sys/brk.2 | 147 | ||||
| -rw-r--r-- | lib/libc/sys/chflags.2 | 159 | ||||
| -rw-r--r-- | lib/libc/sys/execve.2 | 268 | ||||
| -rw-r--r-- | lib/libc/sys/getdirentries.2 | 158 | ||||
| -rw-r--r-- | lib/libc/sys/getfsstat.2 | 165 | ||||
| -rw-r--r-- | lib/libc/sys/getitimer.2 | 165 | ||||
| -rw-r--r-- | lib/libc/sys/getsockopt.2 | 347 | ||||
| -rw-r--r-- | lib/libc/sys/gettimeofday.2 | 127 | ||||
| -rw-r--r-- | lib/libc/sys/intro.2 | 674 | ||||
| -rw-r--r-- | lib/libc/sys/mmap.2 | 214 | ||||
| -rw-r--r-- | lib/libc/sys/mount.2 | 295 | ||||
| -rw-r--r-- | lib/libc/sys/msync.2 | 90 | ||||
| -rw-r--r-- | lib/libc/sys/munmap.2 | 78 | ||||
| -rw-r--r-- | lib/libc/sys/quotactl.2 | 213 | ||||
| -rw-r--r-- | lib/libc/sys/sigaltstack.2 | 165 | ||||
| -rw-r--r-- | lib/libc/sys/sigsuspend.2 | 80 | ||||
| -rw-r--r-- | lib/libc/sys/stat.2 | 266 | ||||
| -rw-r--r-- | lib/libc/sys/statfs.2 | 178 | ||||
| -rw-r--r-- | lib/libc/sys/undelete.2 | 105 |
20 files changed, 4004 insertions, 0 deletions
diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc new file mode 100644 index 000000000000..c89e36e2bd10 --- /dev/null +++ b/lib/libc/sys/Makefile.inc @@ -0,0 +1,110 @@ +# @(#)Makefile.inc 8.3 (Berkeley) 10/24/94 + +# sys sources +.PATH: ${.CURDIR}/${MACHINE}/sys ${.CURDIR}/sys + +# modules with non-default implementations on at least one architecture: +SRCS+= Ovfork.s brk.s cerror.s exect.s fork.s pipe.s ptrace.s reboot.s \ + sbrk.s setlogin.s sigpending.s sigprocmask.s sigreturn.s \ + sigsuspend.s syscall.s + +# glue to provide compatibility between GCC 1.X and 2.X +SRCS+= ftruncate.c lseek.c mmap.c truncate.c + +# modules with default implementations on all architectures: +ASM= accept.o access.o acct.o adjtime.o bind.o chdir.o chflags.o chmod.o \ + chown.o chroot.o close.o connect.o dup.o dup2.o execve.o fchdir.o \ + fchflags.o fchmod.o fchown.o fcntl.o flock.o fpathconf.o fstat.o \ + fstatfs.o fsync.o getdirentries.o getdtablesize.o getegid.o \ + geteuid.o getfh.o getfsstat.o getgid.o getgroups.o getitimer.o \ + getpeername.o getpgrp.o getpid.o getppid.o getpriority.o \ + getrlimit.o getrusage.o getsockname.o getsockopt.o gettimeofday.o \ + getuid.o ioctl.o kill.o ktrace.o lfs_bmapv.o lfs_markv.o \ + lfs_segclean.o lfs_segwait.o link.o listen.o lstat.o \ + madvise.o mincore.o mkdir.o mkfifo.o mknod.o mlock.o mount.o \ + mprotect.o msync.o munlock.o munmap.o nfssvc.o open.o \ + pathconf.o profil.o quotactl.o read.o \ + readlink.o readv.o recvfrom.o recvmsg.o rename.o revoke.o rmdir.o \ + select.o sendmsg.o sendto.o setegid.o seteuid.o setgid.o \ + setgroups.o setitimer.o setpgid.o setpriority.o setrlimit.o \ + setsid.o setsockopt.o settimeofday.o setuid.o shutdown.o \ + sigaction.o sigaltstack.o socket.o socketpair.o stat.o statfs.o \ + swapon.o symlink.o sync.o umask.o undelete.o unlink.o unmount.o \ + utimes.o vadvise.o wait4.o write.o writev.o __syscall.o __sysctl.o + +PSEUDO= _exit.o _getlogin.o + +OBJS+= ${ASM} ${PSEUDO} +POBJS+= ${ASM:.o=.po} ${PSEUDO:.o=.po} +CLEANFILES+=${ASM} ${PSEUDO} ${POBJS} + +${ASM}: ${.CURDIR}/${MACHINE}/SYS.h /usr/include/sys/syscall.h + @echo creating ${.PREFIX}.o ${.PREFIX}.po + @printf '#include "SYS.h"\nRSYSCALL(${.PREFIX})\n' | \ + ${CPP} ${CFLAGS:M-[ID]*} ${AINC} | ${AS} -o ${.PREFIX}.o + @${LD} -x -r ${.PREFIX}.o + @mv a.out ${.PREFIX}.o + @printf '#include "SYS.h"\nRSYSCALL(${.PREFIX})\n' | \ + ${CPP} -DPROF ${CFLAGS:M-[ID]*} ${AINC} | ${AS} -o ${.PREFIX}.po + @${LD} -x -r ${.PREFIX}.po + @mv a.out ${.PREFIX}.po + +${PSEUDO}: ${.CURDIR}/${MACHINE}/SYS.h /usr/include/sys/syscall.h + @echo creating ${.PREFIX}.o ${.PREFIX}.po + @printf '#include "SYS.h"\nPSEUDO(${.PREFIX},${.PREFIX:S/_//})\n' | \ + ${CPP} ${CFLAGS:M-[ID]*} ${AINC} | ${AS} -o ${.PREFIX}.o + @${LD} -x -r ${.PREFIX}.o + @mv a.out ${.PREFIX}.o + @printf '#include "SYS.h"\nPSEUDO(${.PREFIX},${.PREFIX:S/_//})\n' | \ + ${CPP} -DPROF ${CFLAGS:M-[ID]*} ${AINC} | ${AS} -o ${.PREFIX}.po + @${LD} -x -r ${.PREFIX}.po + @mv a.out ${.PREFIX}.po + +MAN2+= accept.0 access.0 acct.0 adjtime.0 bind.0 brk.0 chdir.0 chflags.0 \ + chmod.0 chown.0 chroot.0 close.0 connect.0 dup.0 execve.0 _exit.0 \ + fcntl.0 flock.0 fork.0 fsync.0 getdirentries.0 getdtablesize.0 \ + getfh.0 getfsstat.0 getgid.0 getgroups.0 getitimer.0 getlogin.0 \ + getpeername.0 getpgrp.0 getpid.0 getpriority.0 getrlimit.0 \ + getrusage.0 getsockname.0 getsockopt.0 gettimeofday.0 getuid.0 \ + intro.0 ioctl.0 kill.0 ktrace.0 link.0 listen.0 lseek.0 \ + mkdir.0 mkfifo.0 mknod.0 madvise.0 mincore.0 mlock.0 mmap.0 \ + mount.0 mprotect.0 msync.0 munmap.0 \ + nfssvc.0 open.0 pathconf.0 pipe.0 profil.0 ptrace.0 quotactl.0 \ + munmap.0 nfssvc.0 open.0 pipe.0 profil.0 ptrace.0 quotactl.0 \ + read.0 readlink.0 reboot.0 recv.0 rename.0 revoke.0 rmdir.0 \ + select.0 send.0 setgroups.0 setpgid.0 setsid.0 setuid.0 shutdown.0 \ + sigaction.0 sigpending.0 sigprocmask.0 sigreturn.0 sigaltstack.0 \ + sigstack.0 sigsuspend.0 socket.0 socketpair.0 stat.0 statfs.0 \ + swapon.0 symlink.0 sync.0 syscall.0 truncate.0 umask.0 unlink.0 \ + undelete.0 utimes.0 vfork.0 wait.0 write.0 + +MLINKS+=brk.2 sbrk.2 +MLINKS+=dup.2 dup2.2 +MLINKS+=chdir.2 fchdir.2 +MLINKS+=chflags.2 fchflags.2 +MLINKS+=chmod.2 fchmod.2 +MLINKS+=chown.2 fchown.2 +MLINKS+=getgid.2 getegid.2 +MLINKS+=getitimer.2 setitimer.2 +MLINKS+=getlogin.2 setlogin.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+=intro.2 errno.2 +MLINKS+=lseek.2 seek.2 +MLINKS+=mlock.2 munlock.2 +MLINKS+=mount.2 unmount.2 +MLINKS+=pathconf.2 fpathconf.2 +MLINKS+=read.2 readv.2 +MLINKS+=recv.2 recvfrom.2 recv.2 recvmsg.2 +MLINKS+=send.2 sendmsg.2 send.2 sendto.2 +MLINKS+=setuid.2 setegid.2 setuid.2 seteuid.2 setuid.2 setgid.2 +MLINKS+=stat.2 fstat.2 stat.2 lstat.2 +MLINKS+=statfs.2 fstatfs.2 +MLINKS+=syscall.2 __syscall.2 +MLINKS+=truncate.2 ftruncate.2 +MLINKS+=wait.2 wait3.2 wait.2 wait4.2 wait.2 waitpid.2 +MLINKS+=write.2 writev.2 diff --git a/lib/libc/sys/brk.2 b/lib/libc/sys/brk.2 new file mode 100644 index 000000000000..e3c825e2a603 --- /dev/null +++ b/lib/libc/sys/brk.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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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. +.\" +.\" @(#)brk.2 8.4 (Berkeley) 5/1/95 +.\" +.Dd May 1, 1995 +.Dt BRK 2 +.Os BSD 4 +.Sh NAME +.Nm brk , +.Nm sbrk +.Nd change data segment size +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Ft char +.Fn *brk "const char *addr" +.Ft char * +.Fn *sbrk "int incr" +.Sh DESCRIPTION +.Bf -symbolic +The brk and sbrk functions are historical curiosities +left over from earlier days before the advent of virtual memory management. +.Ef +The +.Fn brk +function +sets the break or lowest address +of a process's data segment (uninitialized data) to +.Fa addr +(immediately above bss). +Data addressing is restricted between +.Fa addr +and the lowest stack pointer to the stack segment. +Memory is allocated by +.Fa brk +in page size pieces; +if +.Fa addr +is not evenly divisible by the system page size, it is +increased to the next page boundary. +.Pp +.\" The +.\" .Nm sbrk +.\" function +.\" allocates chunks of +.\" .Fa incr +.\" bytes +.\" to the process's data space +.\" and returns an address pointer. +.\" The +.\" .Xr malloc 3 +.\" function utilizes +.\" .Nm sbrk . +.\" .Pp +The current value of the program break is reliably returned by +.Dq Li sbrk(0) +(see also +.Xr end 3 ) . +The +.Xr getrlimit 2 +system call may be used to determine +the maximum permissible size of the +.Em data +segment; +it will not be possible to set the break +beyond the +.Em rlim_max +value returned from a call to +.Xr getrlimit , +e.g. +.Dq etext + rlp\(->rlim_max. +(see +.Xr end 3 +for the definition of +.Em etext ) . +.Sh RETURN VALUES +.Nm Brk +returns 0 if successful; +otherwise -1 with +.Va errno +set to indicate why the allocation failed. +.Nm Sbrk +returns a pointer to the base of the new storage if successful; +otherwise -1 with +.Va errno +set to indicate why the allocation failed. +.Sh ERRORS +.Xr Brk +or +.Xr sbrk +will fail and no additional memory will be allocated if +one of the following are true: +.Bl -tag -width [ENOMEM] +.It Bq Er ENOMEM +The limit, as set by +.Xr setrlimit 2 , +was exceeded. +.It Bq Er ENOMEM +The maximum possible size of a data segment (compiled into the +system) was exceeded. +.It Bq Er ENOMEM +Insufficient space existed in the swap area +to support the expansion. +.El +.Sh SEE ALSO +.Xr execve 2 , +.Xr getrlimit 2 , +.Xr malloc 3 , +.Xr end 3 +.Sh BUGS +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 . +.Sh HISTORY +A +.Nm +function call appeared in Version 7 AT&T UNIX. diff --git a/lib/libc/sys/chflags.2 b/lib/libc/sys/chflags.2 new file mode 100644 index 000000000000..e10d98d5dedd --- /dev/null +++ b/lib/libc/sys/chflags.2 @@ -0,0 +1,159 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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. +.\" +.\" @(#)chflags.2 8.3 (Berkeley) 5/2/95 +.\" +.Dd May 2, 1995 +.Dt CHFLAGS 2 +.Os +.Sh NAME +.Nm chflags , +.Nm fchflags +.Nd set file flags +.Sh SYNOPSIS +.Fd #include <sys/stat.h> +.Fd #include <unistd.h> +.Ft int +.Fn chflags "const char *path" "u_long flags" +.Ft int +.Fn fchflags "int fd" "u_long flags" +.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 flags specified are formed by +.Em or Ns 'ing +the following values +.Pp +.Bl -tag -width "SF_IMMUTABLE" -compact -offset indent +.It UF_NODUMP +Do not dump the file. +.It UF_IMMUTABLE +The file may not be changed. +.It UF_APPEND +The file may only be appended to. +.It UF_OPAQUE +The directory is opaque when viewed through a union stack. +.\".It ARCHIVED +.\"File is archived. +.It SF_IMMUTABLE +The file may not be changed. +.It SF_APPEND +The file may only be appended to. +.El +.Pp +The +.Dq UF_IMMUTABLE +and +.Dq UF_APPEND +flags may be set or unset by either the owner of a file or the super-user. +.Pp +The +.Dq SF_IMMUTABLE +and +.Dq SF_APPEND +flags may only be set or unset by the super-user. +Attempts by the non-super-user to set the super-user only flags +are silently ignored. +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.) +.Sh RETURN VALUES +Upon successful completion, a value of 0 is returned. +Otherwise, -1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +.Fn Chflags +will fail it: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er EINVAL +The pathname contains a character with the high-order bit set. +.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 EROFS +The named file resides on a read-only file system. +.It Bq Er EFAULT +.Fa Path +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. +.El +.Pp +.Fn Fchflags +will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The descriptor is not valid. +.It Bq Er EINVAL +.Fa Fd +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 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. +.El +.Sh SEE ALSO +.Xr chflags 1 , +.Xr init 8 , +.Xr mount_union 8 +.Sh HISTORY +The +.Nm chflags +and +.Nm fchflags +functions first appeared in 4.4BSD. diff --git a/lib/libc/sys/execve.2 b/lib/libc/sys/execve.2 new file mode 100644 index 000000000000..ca44793d731c --- /dev/null +++ b/lib/libc/sys/execve.2 @@ -0,0 +1,268 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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. +.\" +.\" @(#)execve.2 8.5 (Berkeley) 6/1/94 +.\" +.Dd June 1, 1994 +.Dt EXECVE 2 +.Os BSD 4 +.Sh NAME +.Nm execve +.Nd execute a file +.Sh SYNOPSIS +.Fd #include <unistd.h> +.Ft int +.Fn execve "const char *path" "char *const argv[]" "char *const envp[]" +.Sh DESCRIPTION +.Fn Execve +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 . +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 a.out 5 . +.Pp +An interpreter file begins with a line of the form: +.Pp +.Bd -filled -offset indent -compact +.Sy \&#! +.Em interpreter +.Bq Em arg +.Ed +.Pp +When an interpreter file is +.\" was .Fn execve Ap d , +\fBexecve\fP'd, +the system +.\" was .Fn execve Ap s +\fBexecve\fP's +runs 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 +.\" was .Fn execve Ap d +\fBexecve\fP'd +file becomes the second argument; +otherwise, the name of the originally +.\" was .Fn execve Ap d +\fBexecve\fP'd +file becomes the first argument. The original arguments are shifted over to +become the subsequent arguments. The zeroth argument, normally the name of the +.\" was .Fn execve Ap d +\fBexecve\fP'd +file, is left unchanged. +.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 . +.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 ) . +.ne 1i +.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 sigvec 2 , +.Xr sigsetmask 2 +.El +.Pp +When a program is executed as a result of an +.Fn execve +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. +.Sh RETURN VALUES +As the +.Fn execve +function 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 +.Fn Execve +will fail and return to the calling process if: +.Bl -tag -width [ENAMETOOLONG] +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er EINVAL +The pathname contains a character with the high-order bit set. +.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 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 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 or reading by some process. +.ne 1i +.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's argument list +is larger than the system-imposed limit. +The limit in the system as released is 20480 bytes +.Pf ( Dv NCARGS +in +.Ao Pa sys/param.h Ac . +.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 +.Fa Path , +.Fa argv , +or +.Fa envp +point +to an illegal address. +.It Bq Er EIO +An I/O error occurred while reading from the file system. +.El +.Sh CAVEAT +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. +.Sh SEE ALSO +.Xr exit 2 , +.Xr fork 2 , +.Xr execl 3 , +.Xr environ 7 +.Sh HISTORY +The +.Nm +function call appeared in +.Bx 4.2 . diff --git a/lib/libc/sys/getdirentries.2 b/lib/libc/sys/getdirentries.2 new file mode 100644 index 000000000000..532bec151b7f --- /dev/null +++ b/lib/libc/sys/getdirentries.2 @@ -0,0 +1,158 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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. +.\" +.\" @(#)getdirentries.2 8.2 (Berkeley) 5/3/95 +.\" +.Dd May 3, 1995 +.Dt GETDIRENTRIES 2 +.Os +.Sh NAME +.Nm getdirentries +.Nd "get directory entries in a filesystem independent format" +.Sh SYNOPSIS +.Fd #include <sys/dirent.h> +.Ft int +.Fn getdirentries "int fd" "char *buf" "int nbytes" "long *basep" +.Sh DESCRIPTION +.Fn Getdirentries +reads directory entries from the directory +referenced by the file descriptor +.Fa fd +into the buffer pointed to by +.Fa buf , +in a filesystem independent format. +Up to +.Fa nbytes +of data will be transferred. +.Fa Nbytes +must be greater than or equal to the +block size associated with the file, +see +.Xr stat 2 . +Some filesystems may not support +.Fn getdirentries +with buffers smaller than this size. +.Pp +The data in the buffer is a series of +.Em dirent +structures each containing the following entries: +.Bd -literal -offset indent +unsigned long d_fileno; +unsigned short d_reclen; +unsigned char d_type; +unsigned char d_namlen; +char d_name[MAXNAMELEN + 1]; /* see below */ +.Ed +.Pp +The +.Fa d_fileno +entry is a number which is unique for each +distinct file in the filesystem. +Files that are linked by hard links (see +.Xr link 2 ) +have the same +.Fa d_fileno . +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 MAXNAMELEN +\&+ 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 . +A value of zero is returned when +the end of the directory has been reached. +.Pp +.Fn Getdirentries +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 , +or zero. +.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 +.Fn Getdirentries +will fail if: +.Bl -tag -width [EFAULT] +.It EBADF +.Fa fd +is not a valid file descriptor open for reading. +.It EFAULT +Either +.Fa buf +or +.Fa basep +point outside the allocated address space. +.It EIO +An +.Tn I/O +error occurred while reading from or writing to the file system. +.El +.Sh SEE ALSO +.Xr open 2 , +.Xr lseek 2 +.Sh HISTORY +The +.Nm getdirentries +function first appeared in 4.4BSD. diff --git a/lib/libc/sys/getfsstat.2 b/lib/libc/sys/getfsstat.2 new file mode 100644 index 000000000000..b25261cf15ad --- /dev/null +++ b/lib/libc/sys/getfsstat.2 @@ -0,0 +1,165 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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. +.\" +.\" @(#)getfsstat.2 8.3 (Berkeley) 5/25/95 +.\" +.Dd May 25, 1995 +.Dt GETFSSTAT 2 +.Os +.Sh NAME +.Nm getfsstat +.Nd get list of all mounted filesystems +.Sh SYNOPSIS +.Fd #include <sys/param.h> +.Fd #include <sys/ucred.h> +.Fd #include <sys/mount.h> +.Ft int +.Fn getfsstat "struct statfs *buf" "long bufsize" "int flags" +.Sh DESCRIPTION +.Fn Getfsstat +returns information about all mounted filesystems. +.Fa Buf +is a pointer to +.Xr statfs +structures defined as follows: +.Bd -literal +typedef quad fsid_t; + +#define MFSNAMELEN 16 /* length of fs type name, including null */ +#define MNAMELEN 90 /* length of buffer for returned name */ + +struct statfs { + short f_type; /* filesystem type number */ + short f_flags; /* copy of mount flags */ + long f_bsize; /* fundamental file system block size */ + long f_iosize; /* optimal transfer block size */ + long f_blocks; /* total data blocks in file system */ + long f_bfree; /* free blocks in fs */ + long f_bavail; /* free blocks avail to non-superuser */ + long f_files; /* total file nodes in file system */ + long f_ffree; /* free file nodes in fs */ + fsid_t f_fsid; /* file system id */ + uid_t f_owner; /* user that mounted the filesystem */ + long f_spare[4]; /* spare for later */ + char f_fstypename[MFSNAMELEN]; /* fs type name */ + char f_mntonname[MNAMELEN]; /* directory on which mounted */ + char f_mntfromname[MNAMELEN];/* mounted filesystem */ +}; +.Ed +.Pp +The flags that may be returned include: +.Bl -tag -width MNT_ASYNCHRONOUS +.It Dv MNT_RDONLY +The filesystem is mounted read-only; +Even the super-user may not write on it. +.It Dv MNT_NOEXEC +Files may not be executed from the filesystem. +.It Dv MNT_NOSUID +Setuid and setgid bits on files are not honored when they are executed. +.It Dv MNT_NODEV +Special files in the filesystem may not be opened. +.It Dv MNT_SYNCHRONOUS +All I/O to the filesystem is done synchronously. +.It Dv MNT_ASYNCHRONOUS +No filesystem I/O is done synchronously. +.It Dv MNT_LOCAL +The filesystem resides locally. +.It Dv MNT_QUOTA +The filesystem has quotas enabled on it. +.It Dv MNT_ROOTFS +Identifies the root filesystem. +.It Dv MNT_EXRDONLY +The filesystem is exported read-only. +.It Dv MNT_EXPORTED +The filesystem is exported for both reading and writing. +.It Dv MNT_DEFEXPORTED +The filesystem is exported for both reading and writing to any Internet host. +.It Dv MNT_EXPORTANON +The filesystem maps all remote accesses to the anonymous user. +.It Dv MNT_EXKERB +The filesystem is exported with Kerberos uid mapping. +.El +.Pp +Fields that are undefined for a particular filesystem are set to -1. +The buffer is filled with an array of +.Fa fsstat +structures, one for each mounted filesystem +up to the size specified by +.Fa bufsize . +.Pp +If +.Fa buf +is given as NULL, +.Fn getfsstat +returns just the number of mounted filesystems. +.Pp +Normally +.Fa flags +should be specified as +.Dv MNT_WAIT . +If +.Fa flags +is set to +.Dv MNT_NOWAIT , +.Fn getfsstat +will return the information it has available without requesting +an update from each filesystem. +Thus, some of the information will be out of date, but +.Fn getfsstat +will not block waiting for information from a filesystem that is +unable to respond. +.Sh RETURN VALUES +Upon successful completion, the number of +.Fa fsstat +structures is returned. +Otherwise, -1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +.Fn Getfsstat +fails if one or more of the following are true: +.Bl -tag -width Er +.It EFAULT +.Fa Buf +points to an invalid address. +.It EIO +An +.Tn I/O +error occurred while reading from or writing to the filesystem. +.El +.Sh SEE ALSO +.Xr statfs 2 , +.Xr fstab 5 , +.Xr mount 8 +.Sh HISTORY +The +.Nm getfsstat +function first appeared in 4.4BSD. diff --git a/lib/libc/sys/getitimer.2 b/lib/libc/sys/getitimer.2 new file mode 100644 index 000000000000..f39501d66f41 --- /dev/null +++ b/lib/libc/sys/getitimer.2 @@ -0,0 +1,165 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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. +.\" +.\" @(#)getitimer.2 8.3 (Berkeley) 5/16/95 +.\" +.Dd May 16, 1995 +.Dt GETITIMER 2 +.Os BSD 4.2 +.Sh NAME +.Nm getitimer , +.Nm setitimer +.Nd get/set value of interval timer +.Sh SYNOPSIS +.Fd #include <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" "struct itimerval *value" "struct itimerval *ovalue" +.Sh DESCRIPTION +The system provides each process with three interval timers, +defined in +.Ao Pa sys/time.h Ac . +The +.Fn getitimer +call returns the current value for the timer specified in +.Fa which +in the structure at +.Fa value . +The +.Fn setitimer +call sets a timer to the specified +.Fa value +(returning the previous value of the timer if +.Fa ovalue +is non-nil). +.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. 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. +.Sh NOTES +Three macros for manipulating time values are defined in +.Ao Pa sys/time.h Ac . +.Fa Timerclear +sets a time value to zero, +.Fa timerisset +tests if a time value is non-zero, and +.Fa timercmp +compares two time values. +.Sh RETURN VALUES +If the calls succeed, a value of 0 is returned. If an error occurs, +the value -1 is returned, and a more precise error code is placed +in the global variable +.Va errno . +.Sh ERRORS +.Fn Getitimer +and +.Fn setitimer +will fail if: +.Bl -tag -width Er +.It Bq Er EFAULT +The +.Fa value +parameter specified a bad address. +.It Bq Er EINVAL +A +.Fa value +parameter specified a time that was too large +to be handled. +.El +.Sh SEE ALSO +.Xr select 2 , +.Xr sigvec 2 , +.Xr gettimeofday 2 +.Sh HISTORY +The +.Nm +function call appeared in +.Bx 4.2 . diff --git a/lib/libc/sys/getsockopt.2 b/lib/libc/sys/getsockopt.2 new file mode 100644 index 000000000000..8362d5e26805 --- /dev/null +++ b/lib/libc/sys/getsockopt.2 @@ -0,0 +1,347 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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. +.\" +.\" @(#)getsockopt.2 8.4 (Berkeley) 5/2/95 +.\" +.Dd May 2, 1995 +.Dt GETSOCKOPT 2 +.Os BSD 4.3r +.Sh NAME +.Nm getsockopt , +.Nm setsockopt +.Nd get and set options on sockets +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <sys/socket.h> +.Ft int +.Fn getsockopt "int s" "int level" "int optname" "void *optval" "int *optlen" +.Ft int +.Fn setsockopt "int s" "int level" "int optname" "const void *optval" "int optlen" +.Sh DESCRIPTION +.Fn Getsockopt +and +.Fn setsockopt +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 parameters +.Fa optval +and +.Fa optlen +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 parameter, 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 +.Fa Optname +and any specified options are passed uninterpreted to the appropriate +protocol module for interpretation. +The include file +.Ao Pa sys/socket.h Ac +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 +.Fa int +parameter for +.Fa optval . +For +.Fn setsockopt , +the parameter should be non-zero to enable a boolean option, +or zero if the option is to be disabled. +.Dv SO_LINGER +uses a +.Fa struct linger +parameter, defined in +.Ao Pa sys/socket.h Ac , +which specifies the desired state of the option and the +linger interval (see below). +.Dv SO_SNDTIMEO +and +.Dv SO_RCVTIMEO +use a +.Fa struct timeval +parameter, defined in +.Ao Pa sys/time.h Ac . +.Pp +The following options are recognized at the socket level. +Except as noted, each may be examined with +.Fn getsockopt +and set with +.Fn setsockopt . +.Bl -column SO_OOBINLINE -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_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_TYPE Ta "get the type of the socket (get only)" +.It Dv SO_ERROR Ta "get and clear error on the socket (get only)" +.El +.Pp +.Dv SO_DEBUG +enables debugging in the underlying protocol modules. +.Dv SO_REUSEADDR +indicates that the rules used in validating addresses supplied +in a +.Xr bind 2 +call should allow reuse of local addresses. +.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. +.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. +.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 +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 +call when +.Dv SO_LINGER +is requested). +If +.Dv SO_LINGER +is disabled and a +.Xr close +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. +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 +or +.Xr read +calls without the +.Dv MSG_OOB +flag. +Some protocols always behave as if this option is set. +.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 limit on these values. +.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. +.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 than that returned. +.Pp +.Dv SO_SNDTIMEO +is an option to set a timeout value for output operations. +It accepts a +.Fa struct timeval +parameter 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. +.Dv SO_RCVTIMEO +is an option to set a timeout value for input operations. +It accepts a +.Fa struct timeval +parameter 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 +Finally, +.Dv SO_TYPE +and +.Dv SO_ERROR +are options used only with +.Fn getsockopt . +.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_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. +.Sh RETURN VALUES +A 0 is returned if the call succeeds, -1 if it fails. +.Sh ERRORS +The call succeeds unless: +.Bl -tag -width ENOPROTOOPTAA +.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. +.El +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr socket 2 , +.Xr getprotoent 3 +.Xr protocols 5 +.Sh BUGS +Several of the socket options should be handled at lower levels of the system. +.Sh HISTORY +The +.Nm +system call appeared in +.Bx 4.2 . diff --git a/lib/libc/sys/gettimeofday.2 b/lib/libc/sys/gettimeofday.2 new file mode 100644 index 000000000000..b4d04295c7e3 --- /dev/null +++ b/lib/libc/sys/gettimeofday.2 @@ -0,0 +1,127 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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. +.\" +.\" @(#)gettimeofday.2 8.2 (Berkeley) 5/26/95 +.\" +.Dd May 26, 1995 +.Dt GETTIMEOFDAY 2 +.Os BSD 4 +.Sh NAME +.Nm gettimeofday , +.Nm settimeofday +.Nd get/set date and time +.Sh SYNOPSIS +.Fd #include <sys/time.h> +.Ft int +.Fn gettimeofday "struct timeval *tp" "struct timezone *tzp" +.Ft int +.Fn settimeofday "struct timeval *tp" "struct timezone *tzp" +.Sh DESCRIPTION +.Bf -symbolic +Note: timezone is no longer used; this information is kept outside +the kernel. +.Ef +The system's notion of the current Greenwich time and the current time +zone is obtained with the +.Fn gettimeofday +call, and set with the +.Fn settimeofday +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 ``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 +.Ao Pa sys/time.h Ac +as: +.Pp +.Bd -literal +struct timeval { + long tv_sec; /* seconds since Jan. 1, 1970 */ + long tv_usec; /* and microseconds */ +}; + +struct timezone { + int tz_minuteswest; /* of Greenwich */ + int tz_dsttime; /* type of dst correction to apply */ +}; +.Ed +.Pp +The +.Fa 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. +.Pp +Only the super-user may set the time of day or time zone. +If the system is running in secure mode (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. +.Sh RETURN +A 0 return value indicates that the call succeeded. +A -1 return value indicates an error occurred, and in this +case an error code is stored into the global variable +.Va errno . +.Sh ERRORS +The following error codes may be set in +.Va errno : +.Bl -tag -width [EFAULT] +.It Bq Er EFAULT +An argument address referenced invalid memory. +.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 ctime 3 , +.Xr timed 8 +.Sh HISTORY +The +.Nm +function call appeared in +.Bx 4.2 . diff --git a/lib/libc/sys/intro.2 b/lib/libc/sys/intro.2 new file mode 100644 index 000000000000..ddda2ba6aada --- /dev/null +++ b/lib/libc/sys/intro.2 @@ -0,0 +1,674 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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. +.\" +.\" @(#)intro.2 8.5 (Berkeley) 2/27/95 +.\" +.Dd February 27, 1995 +.Dt INTRO 2 +.Os BSD 4 +.Sh NAME +.Nm intro +.Nd introduction to system calls and error numbers +.Sh SYNOPSIS +.Fd #include <sys/errno.h> +.Sh DESCRIPTION +This section provides an overview of the system calls, +their error returns, and other common definitions and concepts. +.\".Pp +.\".Sy System call restart +.\".Pp +.\"<more later...> +.Sh DIAGNOSTICS +Nearly all of the system calls provide an error number in the external +variable +.Va errno , +which is defined as: +.Pp +.Dl extern int errno +.Pp +When a system call detects an error, +it returns an integer value +indicating failure (usually -1) +and sets the variable +.Va errno +accordingly. +<This allows interpretation of the failure on receiving +a -1 and to take action accordingly.> +Successful calls never set +.Va 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 +.Aq Pa sys/errno.h . +.Bl -hang -width Ds +.It Er 0 Em "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 function call" . +An asynchronous signal (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 function 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 (over written) by any subsequent errors. +.It Er 6 ENXIO Em "\&No such device or address" . +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 "Arg list too long" . +The number of bytes used for the argument and environment +list of the new process exceeded the current limit +of 20480 bytes +.Pf ( Dv NCARGS +in +.Aq Pa 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 (write) request was made to a file that was only open for +writing (reading). +.sp +.It Er 10 ECHILD Em "\&No child processes" . +A +.Xr wait +or +.Xr waitpid +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 "Not a block device" . +A block device operation was attempted on a non-block device or file. +.It Er 16 EBUSY Em "Resource 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 +function. +.It Er 18 EXDEV Em "Improper 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 +or +.Xr kill +function). +.It Er 23 ENFILE Em "Too many open files in system" . +Maximum number of file descriptors allowable on the system +has been reached and a requests for an open cannot be satisfied +until at least one has been closed. +.It Er 24 EMFILE Em "Too many open files" . +<As released, the limit on the number of +open files per process is 64.> +.Xr Getdtablesize 2 +will obtain the current limit. +.It Er 25 ENOTTY Em "Inappropriate ioctl for device" . +A control function (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 (shared text) file +which was open for writing by another process, or +while the pure procedure file was being executed an +.Xr open +call requested write access. +.It Er 27 EFBIG Em "File too large" . +The size of a file exceeded the maximum (about +.if t 2\u\s-231\s+2\d +.if n 2.1E9 +bytes). +.It Er 28 ENOSPC Em "Device out of space" . +A +.Xr write +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 +function was issued on a socket, pipe or +.Tn FIFO . +.It Er 30 EROFS Em "Read-only file system" . +An attempt was made to modify a file or directory +was made +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 (limit +of 32767 hard links per file). +.It Er 32 EPIPE Em "Broken pipe" . +A write on a pipe, socket or +.Tn 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 "Numerical result out of range" . +A numerical result of the function was too large to fit in the +available space (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 +a +.Xr connect 2 ) +was attempted on a non-blocking object (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 +.Tn ARPA +Internet +.Tn 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 shouldn't necessarily expect to be able to use +.Tn NS +addresses with +.Tn ARPA +Internet protocols. +.It Er 48 EADDRINUSE Em "Address already in use" . +Only one usage of each address is normally permitted. +.sp +.It Er 49 EADDRNOTAVAIL Em "Cannot 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 +request was made on an already connected socket; or, +a +.Xr sendto +or +.Xr sendmsg +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 (when sending on a datagram socket) +no address was supplied. +.It Er 58 ESHUTDOWN Em "Cannot 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 +or +.Xr send +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 8 symbolic links. +.It Er 63 ENAMETOOLONG Em "File name too long" . +A component of a path name exceeded 255 +.Pq Dv MAXNAMELEN +characters, or an entire +path name exceeded 1023 +.Pq Dv MAXPATHLEN Ns -1 +characters. +.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 +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. +.ne 1i +.It Er 70 ESTALE Em "Stale NFS file handle" . +An attempt was made to access an open file (on an +.Tn NFS +filesystem) +which is now unavailable as referenced by the file descriptor. +This may indicate the file was deleted on the +.Tn NFS +server or some +other catastrophic event occurred. +.It Er 72 EBADRPC Em "RPC struct is bad" . +Exchange of +.Tn RPC +information was unsuccessful. +.It Er 73 ERPCMISMATCH Em "RPC version wrong" . +The version of +.Tn 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 Tn RPC . +.It Er 76 EPROCUNAVAIL Em "Bad procedure for program" . +An +.Tn RPC +call was attempted for a procedure which doesn't 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. +.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 30000. +.It Parent process ID +A new process is created by a currently active process; (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 a system process, +.Xr init . +.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 (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 (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. +.ne 1i +.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; +(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 changed to be +.Xr init , +which is in a separate session. +Not all members of an orphaned process group are necessarily orphaned +processes (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 (possibly by one its ancestors) (see +.Xr execve 2 ) . +By convention, the effective group ID (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 (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 (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 (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. +.ne 1i +.It Special Processes +The processes with process IDs of 0, 1, and 2 are special. +Process 0 is the scheduler. Process 1 is the initialization process +.Xr init , +and is the ancestor of every other process in the system. +It is used to control the process structure. +Process 2 is the paging daemon. +.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 255 +.Pq Dv MAXNAMELEN +characters may be used to name +an ordinary file, special file, or directory. +.Pp +These characters may be selected from the set of all +.Tn ASCII +character +excluding 0 (NUL) and the +.Tn ASCII +code for +.Ql \&/ +(slash). (The parity bit, +bit 7, must be 0.) +.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 +.Tn 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 1024 +.Pq Dv MAXPATHLEN +characters. +.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 (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: +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 +.Pp +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. +.Sh SEE ALSO +.Xr intro 3 , +.Xr perror 3 diff --git a/lib/libc/sys/mmap.2 b/lib/libc/sys/mmap.2 new file mode 100644 index 000000000000..73131349831f --- /dev/null +++ b/lib/libc/sys/mmap.2 @@ -0,0 +1,214 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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. +.\" +.\" @(#)mmap.2 8.4 (Berkeley) 5/11/95 +.\" +.Dd "May 11, 1995" +.Dt MMAP 2 +.Os BSD 4 +.Sh NAME +.Nm mmap +.Nd map files or devices into memory +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <sys/mman.h> +.Ft caddr_t +.Fn mmap "caddr_t addr" "size_t len" "int prot" "int flags" "int fd" "off_t offset" +.Sh DESCRIPTION +The +.Nm mmap +function 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 pagesize, 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 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 MAP_FIXEDX +.It Dv PROT_EXEC +Pages may be executed. +.It Dv PROT_READ +Pages may be read. +.It Dv PROT_WRITE +Pages may be written. +.El +.Pp +The +.Fa flags +parameter 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: +.Pp +.Bl -tag -width MAP_FIXEDX +.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 +parameter is ignored. +.\".It Dv MAP_FILE +.\"Mapped from a regular file or character-special device memory. +.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, +.Nm mmap +will fail. +If MAP_FIXED is specified, +.Fa addr +must be a multiple of the pagesize. +Use of this option is discouraged. +.It Dv MAP_HASSEMAPHORE +Notify the kernel that the region may contain semaphores and that special +handling may be necessary. +.It Dv MAP_INHERIT +Permit regions to be inherited across +.Xr exec 2 +system calls. +.It Dv MAP_PRIVATE +Modifications are private. +.It Dv MAP_SHARED +Modifications are shared. +.El +.Pp +The +.Xr close 2 +function does not unmap pages, see +.Xr munmap 2 +for further information. +.Pp +The current design does not allow a process to specify the location of +swap space. +In the future we may define an additional mapping type, +.Dv MAP_SWAP , +in which +the file descriptor argument specifies a file or device to which swapping +should be done. +.Sh RETURN VALUES +Upon successful completion, +.Nm mmap +returns a pointer to the mapped region. +Otherwise, a value of -1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +.Fn Mmap +will fail if: +.Bl -tag -width Er +.It Bq Er EACCES +The flag +.Dv PROT_READ +was specified as part of the +.Fa prot +parameter 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 +parameters and +.Fa fd +was not open for writing. +.It Bq Er EBADF +.Fa Fd +is not a valid open file descriptor. +.It Bq Er EINVAL +.\"One of +.\".Dv MAP_ANON +.\"or +.\".Dv MAP_FILE +.\"was not specified as part of the +.\".Fa flags +.\"parameter. +.Dv MAP_FIXED +was specified and the +.Fa addr +parameter was not page aligned or was outside of the +valid address range for a process. +.Dv MAP_ANON was specified and +.Fa fd +was not \-1. +.Fa Fd +did not reference a regular or character special file. +.Fa Len +was less than zero. +.It Bq Er ENOMEM +.Dv MAP_FIXED +was specified and the +.Fa addr +parameter wasn't available. +.Dv MAP_ANON +was specified and insufficient memory was available. +.Sh "SEE ALSO" +.Xr getpagesize 2 , +.Xr msync 2 , +.Xr munmap 2 , +.Xr mprotect 2 , +.Xr madvise 2 , +.Xr mincore 2 diff --git a/lib/libc/sys/mount.2 b/lib/libc/sys/mount.2 new file mode 100644 index 000000000000..0d95386ec3f1 --- /dev/null +++ b/lib/libc/sys/mount.2 @@ -0,0 +1,295 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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. +.\" +.\" @(#)mount.2 8.3 (Berkeley) 5/24/95 +.\" +.Dd May 24, 1995 +.Dt MOUNT 2 +.Os BSD 4 +.Sh NAME +.Nm mount , +.Nm unmount +.Nd mount or dismount a filesystem +.Sh SYNOPSIS +.Fd #include <sys/param.h> +.Fd #include <sys/mount.h> +.Ft int +.Fn mount "int type" "const char *dir" "int flags" "caddr_t data" +.Ft int +.Fn unmount "const char *dir" "int flags" +.Sh DESCRIPTION +The +.Fn mount +function grafts +a filesystem object onto the system file tree +at the point +.Ar dir . +The argument +.Ar data +describes the filesystem object to be mounted. +The argument +.Ar type +tells the kernel how to interpret +.Ar data +(See +.Ar type +below). +The contents of the filesystem +become available through the new mount point +.Ar dir . +Any files in +.Ar dir +at the time +of a successful mount are swept under the carpet so to speak, and +are unavailable until the filesystem is unmounted. +.Pp +The following +.Ar flags +may be specified to +suppress default semantics which affect filesystem access. +.Bl -tag -width MNT_SYNCHRONOUS +.It Dv MNT_RDONLY +The filesystem should be treated as read-only; +Even the super-user may not write on it. +.It Dv MNT_NOEXEC +Do not allow files to be executed from the filesystem. +.It Dv MNT_NOSUID +Do not honor setuid or setgid bits on files when executing them. +.It Dv MNT_NODEV +Do not interpret special files on the filesystem. +.It Dv MNT_SYNCHRONOUS +All I/O to the filesystem should be done synchronously. +.El +.Pp +The flag +.Dv MNT_UPDATE +indicates that the mount command is being applied +to an already mounted filesystem. +This allows the mount flags to be changed without requiring +that the filesystem be unmounted and remounted. +Some filesystems may not allow all flags to be changed. +For example, +most filesystems will not allow a change from read-write to read-only. +.Pp +The +.Fa type +argument names the filesystem. +The types of filesystems known to the system can be obtained with +.Xr sysctl 8 +by using the command: +.Bd -literal -offset indent +sysctl vfs +.Ed +.Pp +.Fa Data +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 filesystem. +By convention filesystem manual pages are named +by prefixing ``mount_'' to the name of the filesystem as returned by +.Xr sysctl 8 . +Thus the +.Nm NFS +filesystem is described by the +.Xr mount_nfs 8 +manual page. +.Pp +The +.Fn umount +function call disassociates the filesystem from the specified +mount point +.Fa dir . +.Pp +The +.Fa flags +argument may specify +.Dv MNT_FORCE +to specify that the filesystem 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 filesystem is later remounted. +.Sh RETURN VALUES +The +.Fn mount +returns the value 0 if the mount was successful, otherwise -1 is returned +and the variable +.Va errno +is set to indicate the error. +.Pp +.Nm Umount +returns the value 0 if the umount succeeded; otherwise -1 is returned +and the variable +.Va errno +is set to indicate the error. +.Sh ERRORS +.Fn Mount +will fail when one of the following occurs: +.Bl -tag -width [ENOTBLK] +.It Bq Er EPERM +The caller is not the super-user. +.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 +.Ar name +is not a directory, +or a path prefix of +.Ar special +is not a directory. +.It Bq Er EINVAL +A pathname contains a character with the high-order bit set. +.It Bq Er EBUSY +Another process currently holds a reference to +.Fa dir . +.It Bq Er EFAULT +.Fa Dir +points outside the process's allocated address space. +.El +.Pp +The following errors can occur for a +.Em ufs +filesystem mount: +.Bl -tag -width [ENOTBLK] +.It Bq Er ENODEV +A component of ufs_args +.Ar fspec +does not exist. +.It Bq Er ENOTBLK +.Ar Fspec +is not a block device. +.It Bq Er ENXIO +The major device number of +.Ar fspec +is out of range (this indicates no device driver exists +for the associated hardware). +.It Bq Er EBUSY +.Ar Fspec +is already mounted. +.It Bq Er EMFILE +No space remains in the mount table. +.It Bq Er EINVAL +The super block for the filesystem had a bad magic +number or an out of range block size. +.It Bq Er ENOMEM +Not enough memory was available to read the cylinder +group information for the filesystem. +.It Bq Er EIO +An I/O error occurred while reading the super block or +cylinder group information. +.It Bq Er EFAULT +.Ar Fspec +points outside the process's allocated address space. +.El +.Pp +The following errors can occur for a +.Em nfs +filesystem mount: +.Bl -tag -width [ENOTBLK] +.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 following errors can occur for a +.Em mfs +filesystem mount: +.Bl -tag -width [ENOTBLK] +.It Bq Er EMFILE +No space remains in the mount table. +.It Bq Er EINVAL +The super block for the filesystem had a bad magic +number or an out of range block size. +.It Bq Er ENOMEM +Not enough memory was available to read the cylinder +group information for the filesystem. +.It Bq Er EIO +A paging error occurred while reading the super block or +cylinder group information. +.It Bq Er EFAULT +.Em Name +points outside the process's allocated address space. +.El +.Pp +.Nm Umount +may fail with one of the following errors: +.Bl -tag -width [ENOTBLK] +.It Bq Er EPERM +The caller is not the super-user. +.It Bq Er ENOTDIR +A component of the path is not a directory. +.It Bq Er EINVAL +The pathname contains a character with the high-order bit set. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EINVAL +The requested directory is not in the mount table. +.It Bq Er EBUSY +A process is holding a reference to a file located +on the filesystem. +.It Bq Er EIO +An I/O error occurred while writing cached filesystem information. +.It Bq Er EFAULT +.Fa Dir +points outside the process's allocated address space. +.El +.Pp +A +.Em ufs +or +.Em mfs +mount can also fail if the maximum number of filesystems are currently +mounted. +.Sh SEE ALSO +.Xr mount 8 , +.Xr umount 8 , +.Xr sysctl 8 +.Sh BUGS +Some of the error codes need translation to more obvious messages. +.Sh HISTORY +.Fn Mount +and +.Fn umount +function calls appeared in Version 6 AT&T UNIX. diff --git a/lib/libc/sys/msync.2 b/lib/libc/sys/msync.2 new file mode 100644 index 000000000000..2e648c4725ae --- /dev/null +++ b/lib/libc/sys/msync.2 @@ -0,0 +1,90 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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. +.\" +.\" @(#)msync.2 8.2 (Berkeley) 6/21/94 +.\" +.Dd June 21, 1994 +.Dt MSYNC 2 +.Os +.Sh NAME +.Nm msync +.Nd synchronize a mapped region +.Sh SYNOPSIS +.Fn msync "caddr_t addr" "int len" +.Sh DESCRIPTION +The +.Fn msync +system call +writes any modified pages back to the filesystem 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 the pages containing +.Fa addr +and +.Fa len +succeeding locations will be examined. +Any required synchronization of memory caches +will also take place at this time. +Filesystem operations on a file that is mapped for shared modifications +are unpredictable except after an +.Fn msync . +.Sh ERRORS +The following errors may be reported: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa addr +parameter was not page aligned. +.It Bq Er EINVAL +The +.Fa addr +parameter did not specify an address part of a mapped region. +.It Bq Er EINVAL +The +.Fa len +parameter was negative. +.It Bq Er EIO +An I/O error occured while writing to the file system. +.Sh SEE ALSO +.Xr madvise 2 , +.Xr munmap 2 , +.Xr mprotect 2 , +.Xr mincore 2 +.Sh HISTORY +The +.Fn msync +function first appeared in 4.4BSD. diff --git a/lib/libc/sys/munmap.2 b/lib/libc/sys/munmap.2 new file mode 100644 index 000000000000..97692afd764b --- /dev/null +++ b/lib/libc/sys/munmap.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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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. +.\" +.\" @(#)munmap.2 8.3 (Berkeley) 5/27/94 +.\" +.Dd May 27, 1994 +.Dt MUNMAP 2 +.Os +.Sh NAME +.Nm munmap +.Nd remove a mapping +.Sh SYNOPSIS +.Fn munmap "caddr_t addr" "size_t len" +.Sh DESCRIPTION +The +.Fn munmap +system call +deletes the mappings for the specified address range, +and causes further references to addresses within the range +to generate invalid memory references. +.Sh RETURN VALUES +Upon successful completion, +.Nm munmap +returns zero. +Otherwise, a value of -1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +.Fn Munmap +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa addr +parameter was not page aligned, the +.Fa len +parameter was negative, or +some part of the region being unmapped is outside the +valid address range for a process. +.Sh "SEE ALSO" +.Xr getpagesize 2 , +.Xr msync 2 , +.Xr munmap 2 , +.Xr mprotect 2 , +.Xr madvise 2 , +.Xr mincore 2 +.Sh HISTORY +The +.Fn munmap +function first appeared in 4.4BSD. diff --git a/lib/libc/sys/quotactl.2 b/lib/libc/sys/quotactl.2 new file mode 100644 index 000000000000..1bcdb8bc67d5 --- /dev/null +++ b/lib/libc/sys/quotactl.2 @@ -0,0 +1,213 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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. +.\" +.\" @(#)quotactl.2 8.2 (Berkeley) 3/10/95 +.\" +.Dd March 10, 1995 +.Dt QUOTACTL 2 +.Os +.Sh NAME +.Nm quotactl +.Nd manipulate filesystem quotas +.Sh SYNOPSIS +.Fd #include <ufs/quota.h> /* for ufs quotas */ +.Ft int +.Fn quotactl "const char *path" "int cmd" "int id" "char *addr" +.Sh DESCRIPTION +The +.Fn quotactl +call enables, disables and +manipulates filesystem quotas. +A quota control command +given by +.Fa cmd +operates on the given filename +.Fa path +for the given user +.Fa id . +The address of an optional command specific data structure, +.Fa addr , +may be given; its interpretation +is discussed below with each command. +.Pp +Currently quotas are supported only for the ``ufs'' filesystem. +For ``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 +and group identifiers. +The ``ufs'' specific commands are: +.Bl -tag -width Q_QUOTAON +.It Dv Q_QUOTAON +Enable disk quotas for the filesystem 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 filesystem 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_GETQUOTA +Get disk quota limits and current usage for the user or group +(as determined by the command type) with identifier +.Fa id . +.Fa Addr +is a pointer to a +.Fa struct dqblk +structure (defined in +.Ao Pa ufs/quota.h Ac ) . +.It Dv Q_SETQUOTA +Set disk quota limits for the user or group +(as determined by the command type) with identifier +.Fa id . +.Fa Addr +is a pointer to a +.Fa struct dqblk +structure (defined in +.Ao Pa ufs/quota.h Ac ) . +The usage fields of the +.Fa dqblk +structure are ignored. +This 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 . +.Fa Addr +is a pointer to a +.Fa struct dqblk +structure (defined in +.Ao Pa ufs/quota.h Ac ) . +Only the usage fields are used. +This 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 +parameters are ignored. +.El +.Sh RETURN VALUES +A successful call returns 0, +otherwise the value -1 is returned and the global variable +.Va errno +indicates the reason for the failure. +.Sh ERRORS +A +.Fn quotactl +call will fail if: +.Bl -tag -width ENAMETOOLONGAA +.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 +.Fa Cmd +or the command type is invalid. +.It Bq Er EINVAL +A pathname contains a character with the high-order bit set. +.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 , +the quota file resides on a read-only filesystem. +.It Bq Er EIO +An +.Tn I/O +error occurred while reading from or writing +to a file containing quotas. +.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 +.Fa Path +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 BUGS +There should be some way to integrate this call with the resource +limit interface provided by +.Xr setrlimit 2 +and +.Xr getrlimit 2 . +.Sh HISTORY +The +.Nm quotactl +function call appeared in +.Bx 4.3 Reno . diff --git a/lib/libc/sys/sigaltstack.2 b/lib/libc/sys/sigaltstack.2 new file mode 100644 index 000000000000..162602538739 --- /dev/null +++ b/lib/libc/sys/sigaltstack.2 @@ -0,0 +1,165 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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. +.\" +.\" @(#)sigaltstack.2 8.2 (Berkeley) 5/1/95 +.\" +.Dd May 1, 1995 +.Dt SIGALTSTACK 2 +.Os BSD 4.2 +.Sh NAME +.Nm sigaltstack +.Nd set and/or get signal stack context +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <signal.h> +.Bd -literal +struct sigaltstack { + caddr_t ss_base; + long ss_size; + int ss_flags; +}; +.Ed +.Ft int +.Fn sigaltstack "const struct sigaltstack *ss" "struct sigaltstack *oss" +.Sh DESCRIPTION +.Fn Sigaltstack +allows users to define an alternate stack on which signals +are to be processed. +If +.Fa ss +is non-zero, +it specifies a pointer to and the size of a +.Em "signal stack" +on which to deliver signals, +and tells the system if the process is currently executing +on that stack. +When a signal's action indicates its handler +should execute on the signal stack (specified with a +.Xr sigaction 2 +call), the system checks to see +if the process is currently executing on that stack. +If the process 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 +If +.Dv SA_DISABLE +is set in +.Fa ss_flags , +.Fa ss_base +and +.Fa ss_size +are ignored and the signal stack will be disabled. +Trying to disable an active stack will cause +.Nm +to return -1 with +.Va errno +set to +.Dv EINVAL . +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 SA_ONSTACK +if the process is currently on a signal stack and +.Dv SA_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_base = malloc(SIGSTKSZ)) == NULL) + /* error return */ +sigstk.ss_size = SIGSTKSZ; +sigstk.ss_flags = 0; +if (sigaltstack(&sigstk,0) < 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 +Upon successful completion, a value of 0 is returned. +Otherwise, a value of -1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +.Fn Sigstack +will fail and the signal stack context will remain unchanged +if one of the following occurs. +.Bl -tag -width [ENOMEM] +.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 EINVAL +An attempt was made to disable an active stack. +.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 +.Nm sigaltstack , +the +.Fn sigstack +system call, appeared in +.Bx 4.2 . diff --git a/lib/libc/sys/sigsuspend.2 b/lib/libc/sys/sigsuspend.2 new file mode 100644 index 000000000000..2fa3c8d3e74a --- /dev/null +++ b/lib/libc/sys/sigsuspend.2 @@ -0,0 +1,80 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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. +.\" +.\" @(#)sigsuspend.2 8.2 (Berkeley) 5/16/95 +.\" +.Dd May 16, 1995 +.Dt SIGSUSPEND 2 +.Os +.Sh NAME +.Nm sigsuspend +.Nd atomically release blocked signals and wait for interrupt +.Sh SYNOPSIS +.Fd #include <signal.h> +.Ft int +.Fn sigsuspend "const sigset_t *sigmask" +.Sh DESCRIPTION +.Fn Sigsuspend +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 . +.Sh RETURN VALUES +The +.Fn sigsuspend +function +always terminates by being interrupted, returning -1 with +.Va errno +set to +.Dv EINTR . +.Sh SEE ALSO +.Xr sigprocmask 2 , +.Xr sigaction 2 , +.Xr sigsetops 3 +.Sh STANDARDS +The +.Nm sigsuspend +function call +conforms to +.St -p1003.1-88 . diff --git a/lib/libc/sys/stat.2 b/lib/libc/sys/stat.2 new file mode 100644 index 000000000000..6c39663b1d0f --- /dev/null +++ b/lib/libc/sys/stat.2 @@ -0,0 +1,266 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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. +.\" +.\" @(#)stat.2 8.4 (Berkeley) 5/1/95 +.\" +.Dd May 1, 1995 +.Dt STAT 2 +.Os BSD 4 +.Sh NAME +.Nm stat , +.Nm lstat , +.Nm fstat +.Nd get file status +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <sys/stat.h> +.Ft int +.Fn stat "const char *path" "struct stat *sb" +.Ft int +.Fn lstat "const char *path" "struct stat *sb" +.Ft int +.Fn fstat "int fd" "struct stat *sb" +.Sh DESCRIPTION +The +.Fn stat +function 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 +.Fn Lstat +is like +.Fn stat +except in the case where 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. +Unlike other filesystem objects, +symbolic links do not have an owner, group, access mode, times, etc. +Instead, these attributes are taken from the directory that +contains the link. +The only attributes returned from an +.Fn lstat +that refer to the symbolic link itself are the file type (S_IFLNK), +size, blocks, and link count (always 1). +.Pp +The +.Fn fstat +obtains the same information about an open file +known by the file descriptor +.Fa fd . +.Pp +The +.Fa sb +argument is a pointer to a +.Fn stat +structure +as defined by +.Aq Pa sys/stat.h +(shown below) +and into which information is placed concerning the file. +.Bd -literal +struct stat { + dev_t st_dev; /* device inode resides on */ + ino_t st_ino; /* inode's number */ + mode_t st_mode; /* inode protection mode */ + nlink_t st_nlink; /* number or hard links to the file */ + uid_t st_uid; /* user-id of owner */ + gid_t st_gid; /* group-id of owner */ + dev_t st_rdev; /* device type, for special file inode */ + struct timespec st_atimespec; /* time of last access */ + struct timespec st_mtimespec; /* time of last data modification */ + struct timespec st_ctimespec; /* time of last file status change */ + off_t st_size; /* file size, in bytes */ + quad_t st_blocks; /* blocks allocated for file */ + u_long st_blksize;/* optimal file sys I/O ops blocksize */ + u_long st_flags; /* user defined flags for file */ + u_long st_gen; /* file generation number */ +}; +.Ed +.Pp +The time-related fields of +.Fa struct stat +are as follows: +.Bl -tag -width XXXst_mtime +.It st_atime +Time when file data last accessed. +Changed by the +.Xr mknod 2 , +.Xr utimes 2 +and +.Xr read 2 +system calls. +.It st_mtime +Time when file data last modified. +Changed by the +.Xr mknod 2 , +.Xr utimes 2 +and +.Xr write 2 +system calls. +.It st_ctime +Time when file status was last changed (inode data modification). +Changed by the +.Xr chmod 2 , +.Xr chown 2 , +.Xr link 2 , +.Xr mknod 2 , +.Xr rename 2 , +.Xr unlink 2 , +.Xr utimes 2 +and +.Xr write 2 +system calls. +.El +.Pp +The size-related fields of the +.Fa struct stat +are as follows: +.Bl -tag -width XXXst_blksize +.It st_blksize +The optimal I/O block size for the file. +.It st_blocks +The 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 status information word +.Fa st_mode +has the following bits: +.Bd -literal +#define S_IFMT 0170000 /* type of file */ +#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_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_IRUSR 0000400 /* read permission, owner */ +#define S_IWUSR 0000200 /* write permission, owner */ +#define S_IXUSR 0000100 /* execute/search permission, owner */ +.Ed +.Pp +For a list of access modes, see +.Aq Pa sys/stat.h , +.Xr access 2 +and +.Xr chmod 2 . +.Sh RETURN VALUES +Upon successful completion a value of 0 is returned. +Otherwise, a value of -1 is returned and +.Va errno +is set to indicate the error. +.Sh COMPATIBILITY +Previous versions of the system used different types for the +.Li st_dev , +.Li st_uid , +.Li st_gid , +.Li st_rdev , +.Li st_size , +.Li st_blksize +and +.Li st_blocks +fields. +.Sh ERRORS +.Fn Stat +and +.Fn lstat +will fail if: +.Bl -tag -width ENAMETOOLONGAA +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er EINVAL +The pathname contains a character with the high-order bit set. +.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 EFAULT +.Fa Sb +or +.Em name +points to an invalid address. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.El +.Pp +.Bl -tag -width [EFAULT] +.Fn Fstat +will fail if: +.It Bq Er EBADF +.Fa fd +is not a valid open file descriptor. +.It Bq Er EFAULT +.Fa Sb +points to an invalid address. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.El +.Sh SEE ALSO +.Xr chmod 2 , +.Xr chown 2 , +.Xr utimes 2 +.Xr symlink 7 +.Sh BUGS +Applying +.Xr fstat +to a socket (and thus to a pipe) +returns a zero'd buffer, +except for the blocksize field, +and a unique device and inode number. +.Sh STANDARDS +The +.Fn stat +and +.Fn fstat +function calls are expected to +conform to IEEE Std 1003.1-1988 +.Pq Dq Tn POSIX . +.Sh HISTORY +A +.Nm lstat +function call appeared in +.Bx 4.2 . diff --git a/lib/libc/sys/statfs.2 b/lib/libc/sys/statfs.2 new file mode 100644 index 000000000000..6db63c6f124c --- /dev/null +++ b/lib/libc/sys/statfs.2 @@ -0,0 +1,178 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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. +.\" +.\" @(#)statfs.2 8.5 (Berkeley) 5/24/95 +.\" +.Dd May 24, 1995 +.Dt STATFS 2 +.Os +.Sh NAME +.Nm statfs +.Nd get file system statistics +.Sh SYNOPSIS +.Fd #include <sys/param.h> +.Fd #include <sys/mount.h> +.Ft int +.Fn statfs "const char *path" "struct statfs *buf" +.Ft int +.Fn fstatfs "int fd" "struct statfs *buf" +.Sh DESCRIPTION +.Fn Statfs +returns information about a mounted file system. +.Fa Path +is the path name of any file within the mounted filesystem. +.Fa Buf +is a pointer to a +.Fn statfs +structure defined as follows: +.Bd -literal +typedef quad fsid_t; + +#define MFSNAMELEN 16 /* length of fs type name, including null */ +#define MNAMELEN 90 /* length of buffer for returned name */ + +struct statfs { + short f_type; /* filesystem type number */ + short f_flags; /* copy of mount flags */ + long f_bsize; /* fundamental file system block size */ + long f_iosize; /* optimal transfer block size */ + long f_blocks; /* total data blocks in file system */ + long f_bfree; /* free blocks in fs */ + long f_bavail; /* free blocks avail to non-superuser */ + long f_files; /* total file nodes in file system */ + long f_ffree; /* free file nodes in fs */ + fsid_t f_fsid; /* file system id */ + uid_t f_owner; /* user that mounted the filesystem */ + long f_spare[4]; /* spare for later */ + char f_fstypename[MFSNAMELEN]; /* fs type name */ + char f_mntonname[MNAMELEN]; /* directory on which mounted */ + char f_mntfromname[MNAMELEN];/* mounted filesystem */ +}; +.Ed +The flags that may be returned include: +.Bl -tag -width MNT_ASYNCHRONOUS +.It Dv MNT_RDONLY +The filesystem is mounted read-only; +Even the super-user may not write on it. +.It Dv MNT_NOEXEC +Files may not be executed from the filesystem. +.It Dv MNT_NOSUID +Setuid and setgid bits on files are not honored when they are executed. +.It Dv MNT_NODEV +Special files in the filesystem may not be opened. +.It Dv MNT_SYNCHRONOUS +All I/O to the filesystem is done synchronously. +.It Dv MNT_ASYNCHRONOUS +No filesystem I/O is done synchronously. +.It Dv MNT_LOCAL +The filesystem resides locally. +.It Dv MNT_QUOTA +The filesystem has quotas enabled on it. +.It Dv MNT_ROOTFS +Identifies the root filesystem. +.It Dv MNT_EXRDONLY +The filesystem is exported read-only. +.It Dv MNT_EXPORTED +The filesystem is exported for both reading and writing. +.It Dv MNT_DEFEXPORTED +The filesystem is exported for both reading and writing to any Internet host. +.It Dv MNT_EXPORTANON +The filesystem maps all remote accesses to the anonymous user. +.It Dv MNT_EXKERB +The filesystem is exported with Kerberos uid mapping. +.El +.Pp +Fields that are undefined for a particular file system are set to -1. +.Fn Fstatfs +returns the same information about an open file referenced by descriptor +.Fa fd . +.Sh RETURN VALUES +Upon successful completion, a value of 0 is returned. +Otherwise, -1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +.Fn Statfs +fails if one or more of the following are true: +.Bl -tag -width ENAMETOOLONGA +.It Bq Er ENOTDIR +A component of the path prefix of +.Fa Path +is not a directory. +.It Bq Er EINVAL +.Fa path +contains a character with the high-order bit set. +.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 +.Fa Buf +or +.Fa path +points to an invalid address. +.It Bq Er EIO +An +.Tn I/O +error occurred while reading from or writing to the file system. +.El +.Pp +.Fn Fstatfs +fails if one or more of the following are true: +.Bl -tag -width ENAMETOOLONGA +.It Bq Er EBADF +.Fa Fd +is not a valid open file descriptor. +.It Bq Er EFAULT +.Fa Buf +points to an invalid address. +.It Bq Er EIO +An +.Tn I/O +error occurred while reading from or writing to the file system. +.El +.Sh HISTORY +The +.Nm statfs +function first appeared in 4.4BSD. diff --git a/lib/libc/sys/undelete.2 b/lib/libc/sys/undelete.2 new file mode 100644 index 000000000000..317397c8d0d8 --- /dev/null +++ b/lib/libc/sys/undelete.2 @@ -0,0 +1,105 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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. +.\" +.\" @(#)undelete.2 8.4 (Berkeley) 10/18/94 +.\" +.Dd October 18, 1994 +.Dt UNDELETE 2 +.Os BSD 4 +.Sh NAME +.Nm undelete +.Nd attempt to recover a deleted file +.Sh SYNOPSIS +.Fd #include <unistd.h> +.Ft int +.Fn undelete "const char *path" +.Sh DESCRIPTION +The +.Fn undelete +function attempts to recover the deleted file named by +.Fa path . +Currently, this works only when the named object +is a whiteout in a union filesystem. +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 +.Nm undelete +functionality may be expanded to other filesystems able to recover +deleted files such as the log-structured filesystem. +.Sh RETURN VALUES +Upon successful completion, a value of 0 is returned. +Otherwise, a value of -1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn undelete +succeeds unless: +.Bl -tag -width ENAMETOOLONGAA +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er EINVAL +The pathname contains a character with the high-order bit set. +.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 EIO +An I/O error occurred while updating the directory entry. +.It Bq Er EROFS +The name resides on a read-only file system. +.It Bq Er EFAULT +.Fa Path +points outside the process's allocated address space. +.El +.Sh SEE ALSO +.Xr unlink 2 , +.Xr mount_union 8 +.Sh HISTORY +An +.Nm undelete +function call first appeared in 4.4BSD-Lite. |