From fc3d7cd22d54b4da1b2b5849c5b980255975b015 Mon Sep 17 00:00:00 2001 From: Alan Cox Date: Thu, 22 Sep 2016 22:42:57 +0100 Subject: [PATCH] man2: a beginning And some test material for marksman --- Applications/man2/_exit.2 | 29 ++++++++++ Applications/man2/close.2 | 35 ++++++++++++ Applications/man2/link.2 | 47 ++++++++++++++++ Applications/man2/mknod.2 | 1 + Applications/man2/open.2 | 111 +++++++++++++++++++++++++++++++++++++ Applications/man2/rename.2 | 58 +++++++++++++++++++ Applications/man2/unlink.2 | 40 +++++++++++++ 7 files changed, 321 insertions(+) create mode 100644 Applications/man2/_exit.2 create mode 100644 Applications/man2/close.2 create mode 100644 Applications/man2/link.2 create mode 100644 Applications/man2/mknod.2 create mode 100644 Applications/man2/open.2 create mode 100644 Applications/man2/rename.2 create mode 100644 Applications/man2/unlink.2 diff --git a/Applications/man2/_exit.2 b/Applications/man2/_exit.2 new file mode 100644 index 00000000..1120eb1d --- /dev/null +++ b/Applications/man2/_exit.2 @@ -0,0 +1,29 @@ +_EXIT(2) +## NAME +_exit - exit a process freeing its resources +## SYNOPSIS +*#include * + +*int _exit*(*int* status); +## DESCRIPTION +Upon calling this function the calling process immediately terminates and frees +up resources. The status value is returned back to the waiting parent via the +*waitpid* call. + +The _exit call does not perform any cleanup specified by *atexit*(3) nor do any +standard I/O cleanup. Processes would normally exit via the *exit*(3) library +function. + +When a process exits it frees its resources and then enters zombie state until +the parent waits for it, unless the parent is ignoring notifications about child +processes, in which case it exits completely and the reported status is lost. +## RETURN VALUE +This function does not return. +## CONFORMING TO +UZI, POSIX.1-2001 +##NOTES +While the exit status argument is an *int* only the low 8bits of the status +passed in exit will be provided to the parent. +## SEE ALSO +*exit*(3),*fork*(2),*waitpid*(2). + diff --git a/Applications/man2/close.2 b/Applications/man2/close.2 new file mode 100644 index 00000000..0fd3bd8e --- /dev/null +++ b/Applications/man2/close.2 @@ -0,0 +1,35 @@ +CLOSE(2) +## NAME +close - close a file descriptor +## SYNOPSIS +*#include * + +*int close*(*int* fd); +## DESCRIPTION +Close a file descriptor that was created with *open*(2), *pipe*(2), *socket*(2), +or other calls that return a file descriptor. If this is the last reference to +this file descriptor then any file locks created with *flock*(2) are closed. + +If *fd* is the last file descriptor referring to the underlying file table entry +then the file table entry is freed. If this is the last reference to the file +object then any resources are freed, devices will go inactive, and any file +that has been removed using *unlink*(2) will be freed on disc. +## RETURN VALUE +On success, zero is returned. On error -1 is returned and errno is set. +## ERRORS +:*EBADF* + An invalid file descriptor was passed. +:*EIO* + An I/O error occurred. +## CONFORMING TO +V7, UZI, POSIX.1-2001, POSIX.1-2008 +## NOTES +The return of a *close*() call does not guarantee that the data is on the +media. If this is required then a call to *sync*(2) is needed. +## BUGS +Many systems provide an *fsync*(2) and *fdatasync*(2) call to write back the +data on just one file. In a small system like Fuzix this is not useful as +*sync*(2) is just as good, but ought to be provided by wrappers in the C +library. +## SEE ALSO +*flock*(2), *open*(2), *pipe*(2), *socket*(2), *sync*(2), *unlink*(2). diff --git a/Applications/man2/link.2 b/Applications/man2/link.2 new file mode 100644 index 00000000..f54c90da --- /dev/null +++ b/Applications/man2/link.2 @@ -0,0 +1,47 @@ +LINK(2) +## NAME +link - add another path to a file +## SYNOPSIS +*#include * + +*int link*(*const char \**from, *const char \**to); +## DESCRIPTION +*link*() adds a new path to an existing file object. The new path must be on +the same file system as the file. Both paths reference the same object +and all the permissions and properties of the file belong to the file not the +name so are shared. + +A file is deleted when the final reference is removed with *unlink*(2) and +nobody holds an open file handle to the file itself. +## RETURN VALUE +On success, zero is returned. On error -1 is returned and errno is set. +## ERRORS +:*EACCES* + Insufficient permission is available to create the new name. +:*EFAULT* + The address passed for the path is invalid. +:*EIO* + An I/O error occurred. +:*EISDIR* + An attempt was made to add a link to a directory. +:*EMLINK* + The new link would give the file more links than the filesystem permits. +:*ENOENT* + The source does not exist, or the target directory does not exist. +:*ENOMEM* + No memory was available. +:*ENOSPC* + No disk space was available for the new name. +:*ENOTDIR* + A path element before the final one was not a directory. +:*EPERM* + There are insufficient permissions to perform the removal or the creation of + the paths. +:*EROFS* + The file system is read-only. +:*EXDEV* + The two paths are not on the same file system. +## CONFORMING TO +V7, UZI, POSIX.1-2001, POSIX.1-2008 +## SEE ALSO +*rename*(2), *unlink*(2). diff --git a/Applications/man2/mknod.2 b/Applications/man2/mknod.2 new file mode 100644 index 00000000..795264ae --- /dev/null +++ b/Applications/man2/mknod.2 @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/Applications/man2/open.2 b/Applications/man2/open.2 new file mode 100644 index 00000000..5027b010 --- /dev/null +++ b/Applications/man2/open.2 @@ -0,0 +1,111 @@ +OPEN(2) +## NAME +open - open an existing file or create a new one +## SYNOPSIS +*#include * + +*int open*(*const char \**path, *int* flags); + +*int open*(*const char \**path, *int* flags, *mode_t* mode); +## DESCRIPTION +The open call accesses the object given by the path, and returns a file descriptor +referencing this object, which remains valid until the last *close*(2). This +file descriptor is then used for other system calls while accessing the object. + +The file descriptor is a reference to a file table entry. The file table entry +references the underlying object. Permissions are checked at open time only. +An open descriptor also ensures the underlying object remains until the final +*close*(2) even if removed from the filesystem by *unlink*(2). The file +table entry is associated with an offset and status flags. Thus the offset +is shared across descriptors duplicated via *fork*(2) or *dup*(2) and *dup2*(2) +calls. + +The flags must indicate the access mode desired. The permitted modes are +*O\_RDONLY*, *O\_WRONLY*, *O\_RDWR*. These request read only, write only, or +read/write access to the object. + +The following additional flags can be included in the open +:*O\_APPEND* +All writes to the file extend the file. Each time a write is made the data +is written to the end of the file and the file offset is set to the end of +file. +:*O\_CLOEXEC* + The file descriptor should be closed when *execve*(2) is invoked and the process + memory image is replaced by something new. +:*O\_CREAT* + If the file does not exist then create it as a new empty file with the mode + calculated from the passed mode and the setting of *umask*(2). Without + this flag an open of a non-existing file reports an error. +:*O\_DIRECT* + Hint that the file is best accessed directly without caching. Cache coherency + with other accessors will be maintained. Useful when large amounts of disk + I/O must be done for data that will be read or written once. +:*O\_EXCL* + If specified with *O\_CREAT* this requires that a new file is created, and will + error if the file already exists. +:*O\_NOCTTY* + If the pathname refers to a *tty*(4) device then do not make this the + controlling terminal even if it would normally do so. +:*O\_NDELAY* + Indicate that neither the open nor any subsequent operation should wait but + instead return an error or partially complete. +:*O\_SYNC* + Hint that the file should be written synchronously, so that the data is on + the media when I/O calls return. +:*O\_TRUNC* + If the file already exists and is being opened for writing then truncate it + back to being empty. + +Many of these flags can be changed at runtime via the *fcntl*(2) call. +## RETURN VALUE +On success, a file descriptor is returned. On error -1 is returned and errno is set. +## ERRORS +:*EACCES* + Insufficient permission is available to move the file. This may be to remove + it from the old location or to create the new name. +:*EAGAIN* + The open request would block and *O\_NDELAY* is specified. +:*EEXIST* + The file already exists and *O\_CREAT* and *O\_EXCL* are set. +:*EFAULT* + One of the addresses passed for the paths is invalid. +:*EINTR* + An open of a device was interrupted by a *signal*(7). +:*EIO* + An I/O error occurred. +:*EISDIR* + An attempt was made to open a directory for writing. +:*EMFILE* + The process already has it's maximum number of files open. +:*ENFILE* + The system wide file descriptor table is full. +:*ENODEV* + The pathname refers to a device node for a device that does not exist. +:*ENOENT* + The source does not exist, or the target directory does not exist. +:*ENOMEM* + No memory was available. +:*ENOTDIR* + A path element before the final one was not a directory. +:*ENXIO* + The pathname refers to a device node for a non existant class of device, or + an attempt wa smade to open a *fifo*(7) with *O\_NDELAY|O\_WRONLY* but there is no + reader. +:*EPERM* + A device or similar special file is imposing it's own restrictions beyond the + filesystem permissions, and may not be opened. +:*EROFS* + The file system is read-only. +## CONFORMING TO +4.3BSD, C89, C99, POSIX.1-2001, POSIX.1-2008 +## NOTES +UZI and early Unix have a separate creat() system call which is semantically +the same as open with the flags O\_CREAT|O\_WRONLY|O\_TRUNC. This is provided by +the C library in FUZIX and modern systems. +## BUGS +Fuzix currently ignores *O\_SYNC* + +FUZIX does not yet implement the *ENXIO* error code for fifo devices. +## SEE ALSO +*close*(2), *creat*(3), *dup*(2), *dup2*(2), *execve*(2), *fcntl*(2), *umask*(2), +*tty*(4), *fifo*(7) diff --git a/Applications/man2/rename.2 b/Applications/man2/rename.2 new file mode 100644 index 00000000..88d91771 --- /dev/null +++ b/Applications/man2/rename.2 @@ -0,0 +1,58 @@ +RENAME(2) +## NAME +rename - change the name or location of a file +## SYNOPSIS +*#include * + +*int rename*(*const char \**from, *const char \**to); +## DESCRIPTION +*rename*() moves a filesystem object from one path to another within a single +filesystem. If the target path already exists then it will be replaced if +possible. As only the name is changed other links and open file handles are not +affected. + +*rename*() is atomic in the sense that the transaction either completes or +fails and the file has either the old or new name but never both barring +media failure. It is not guaranteed that other processes cannot observe both +the old or new names at the same time. +## RETURN VALUE +On success, zero is returned. On error -1 is returned and errno is set. +## ERRORS +:*EACCES* + Insufficient permission is available to move the file. This may be to remove + it from the old location or to create the new name. +:*EFAULT* + One of the addresses passed for the paths is invalid. +:*EINVAL* + An attempt was made to place a directory within itself and create a loop + in the file system. +:*EIO* + An I/O error occurred. +:*EISDIR* + The target is an existing directory. +:*ENOENT* + The source does not exist, or the target directory does not exist. +:*ENOMEM* + No memory was available. +:*ENOSPC* + No disk space was available for the rename. +:*ENOTDIR* + A path element before the final one was not a directory. +:*EPERM* + There are insufficient permissions to perform the removal or the creation of + the paths. +:*EROFS* + The file system is read-only. +:*EXDEV* + The two paths are not on the same file system. +## CONFORMING TO +4.3BSD, C89, C99, POSIX.1-2001, POSIX.1-2008 +## NOTES +Some operating systems permit a rename over an empty directory to succeed. Fuzix +does not. + +This functionality is not present in UZI. +## BUGS +Fuzix does not currently permit the use of *rename*() to move a directory. +## SEE ALSO +*link*(2), *unlink*(2). diff --git a/Applications/man2/unlink.2 b/Applications/man2/unlink.2 new file mode 100644 index 00000000..b2c2c6bf --- /dev/null +++ b/Applications/man2/unlink.2 @@ -0,0 +1,40 @@ +UNLINK(2) +## NAME +unlink - remove a path to a file +## SYNOPSIS +*#include * + +*int unlink*(*const char \**path); +## DESCRIPTION +*unlink*() removes a path to an existing file object. A file is deleted when +the final reference is removed with *unlink*(2) and nobody holds an open +file handle to the file itself. +## RETURN VALUE +On success, zero is returned. On error -1 is returned and errno is set. +## ERRORS +:*EACCES* + Insufficient permission is available to remove the name. +:*EFAULT* + The address passed for the path is invalid. +:*EINVAL* + An attempt was made to place a directory within itself and create a loop + in the file system. +:*EIO* + An I/O error occurred. +:*EISDIR* + An attempt was made to unlink a directory. +:*ENOENT* + The path does not exist. +:*ENOMEM* + No memory was available. +:*ENOTDIR* + A path element before the final one was not a directory. +:*EPERM* + There are insufficient permissions to perform the removal or the creation of + the paths. +:*EROFS* + The file system is read-only. +## CONFORMING TO +V7, UZI, POSIX.1-2001, POSIX.1-2008 +## SEE ALSO +*link*(2), *rename*(2), *rmdir*(2). -- 2.34.1