From 0b4ac2ddff04ce1b012c0940e4e222f35c5b57d8 Mon Sep 17 00:00:00 2001 From: Alan Cox Date: Sat, 24 Sep 2016 16:18:01 +0100 Subject: [PATCH] syscalls: more manual pages --- Applications/man2/chdir.2 | 45 +++++++++++++++++++++++++++++ Applications/man2/fchdir.2 | 1 + Applications/man2/lseek.2 | 59 ++++++++++++++++++++++++++++++++++++++ Applications/man2/sync.2 | 19 ++++++++++++ Applications/man2/write.2 | 55 +++++++++++++++++++++++++++++++++++ 5 files changed, 179 insertions(+) create mode 100644 Applications/man2/chdir.2 create mode 100644 Applications/man2/fchdir.2 create mode 100644 Applications/man2/lseek.2 create mode 100644 Applications/man2/sync.2 create mode 100644 Applications/man2/write.2 diff --git a/Applications/man2/chdir.2 b/Applications/man2/chdir.2 new file mode 100644 index 00000000..b2be6384 --- /dev/null +++ b/Applications/man2/chdir.2 @@ -0,0 +1,45 @@ +CHDIR(2) +## NAME +chdir - change working directory +## SYNOPSIS +*#include * + +*int chdir*(*const char \**path);\ + +*int fchdir*(*int* fd); +## DESCRIPTION +The *chdir*() call changes the current working directory of the caller to +that specified by *path*. + +The *fchdir* call changes the current working directory to that referred to +by *fd*. +## RETURN VALUE +On success, zero is returned. On error -1 is returned and errno is set. +## ERRORS +:*EACCES* + Insufficient permission is available to walk the path +:*EBADF* + The file descriptor *fd* is not valid. +:*EFAULT* + The address passed for the path is invalid. +:*EIO* + An I/O error occurred. +:*ENOENT* + The path does not exist. +:*ENOMEM* + No memory was available. +:*ENOTDIR* + An element of the path is not a directory or *fd* does not + refer to a directory +## CONFORMING TO +V7, UZI, POSIX.1-2001. +## NOTES +It is possible to save and restore the current working directory as follows + + int fd = open(".", O_RDONLY); + ... + fchdir(fd); + close(fd); + +## SEE ALSO +*chroot*(2), *getcwd*(3). diff --git a/Applications/man2/fchdir.2 b/Applications/man2/fchdir.2 new file mode 100644 index 00000000..be67b5fa --- /dev/null +++ b/Applications/man2/fchdir.2 @@ -0,0 +1 @@ +#CHDIR(2) diff --git a/Applications/man2/lseek.2 b/Applications/man2/lseek.2 new file mode 100644 index 00000000..264df7cf --- /dev/null +++ b/Applications/man2/lseek.2 @@ -0,0 +1,59 @@ +LSEEK(2) +## NAME +lseek - set or report the file offset +## SYNOPSIS +*#include *\ + +*#include * + +*off\_t lseek*(*int* fd, *off\_t* offset, int whence); +## DESCRIPTION +The *lseek*() call allows the offset of the file table entry referred to by +file descriptor *fd* to be queried or changed. + +The *whence* value controls the nature of the change and three behaviours are +available. + +:*SEEK\_SET* + The offset is set to *offset* characters into the file. +:*SEEK\_CUR* + The offset is moved relative to the current position. +:*SEEK\_END* + The offset is set relative to the end of file. The offset passed must be + zero or negative. + +Fuzix permits the offset to be set beyond the current end of file. The end of +file position is not changed by this action, but a write of data at that +position will extend the file. +## RETURN VALUE +If the operation succeeds the previous value of the offset is returned. If an +error occurs (off\_t)-1 is returned, errno is set and the offset remains +unmodified. +## ERRORS +:*EBADF* + The file descriptor *fd* is not open. +:*EFAULT* + The address passed for the arguments is invalid. +:*EINVAL* + The *whence* value is not valid, or the resulting offset is negative or beyond + the permitted maximum size of the object. +:*EIO* + An I/O error occurred. +:*EOVERFLOW* + The resulting file offset does not fit in an off\_t. +:*ESPIPE: + The file descriptor points to an object (eg a pipe) that does not support + the lseek operation. +## CONFORMING TO +V7, POSIX.1-2001. +## NOTES +The current file position can be read without modification by calling\ + +*lseek*(*fd*, 0, 0) + +Fuzix implements lseek as a wrapper around an _lseek system call entry. + +Fuzix will not currently report *EOVERFLOW*. +## SEE ALSO +*lseek*(2), *open*(2), *write*(2). + diff --git a/Applications/man2/sync.2 b/Applications/man2/sync.2 new file mode 100644 index 00000000..e8000d82 --- /dev/null +++ b/Applications/man2/sync.2 @@ -0,0 +1,19 @@ +SYNC(2) +## NAME +sync - write changes to stable storage +## SYNOPSIS +*#include * + +*void sync*(*void*);\ + +## DESCRIPTION +When *sync*() is called all buffered modifications to files and to metadata are +committed to the underlying storage. +## RETURN VALUE +None. +## ERRORS +None. +## CONFORMING TO +V7, UZI, POSIX.1-2001. +## SEE ALSO +*fdatasync*(3), *fsync*(3) diff --git a/Applications/man2/write.2 b/Applications/man2/write.2 new file mode 100644 index 00000000..1ffa1b00 --- /dev/null +++ b/Applications/man2/write.2 @@ -0,0 +1,55 @@ +WRITE(2) +## NAME +write - write data to a file descriptor +## SYNOPSIS +*#include * + +*ssize\_t write*(*int* fd, *const void* \*buf, *size\_t* count); +## DESCRIPTION +The *write*() call writes up to the specified *count* of bytes from the buffer +*buf* to the object referenced by file descriptor *fd*. + +On files that support seeking the write begins at the current file offset and +the file offset is incremented by the number of bytes writren. A write will extend +the file. If the *O\_APPEND* flag was specified for this file then the file +offset is set to the end of the file before the write occurs, and it and the +write occur as one atomic operation. + +If the count is zero then zero will be returned. If the count is larger than +*SSIZE\_MAX* an error will be returned. + +A write from a device such as a *socket*(4), *tty*(4) or *fifo*(7) may block and +wait for space to write data. This behaviour is controlled by the *O\_NDELAY* +flag when opening the file. Waiting *write* calls may also be interrupted by a +*signal*(7). +## RETURN VALUE +On success, the number of bytes successfully written is returned. +If no data could be written due to an error then -1 is returned and errno is set. +## ERRORS +:*EAGAIN* + The write would block but the *O\_NDELAY* flag is set on the file descriptor. +:*EBADF* + The file descriptor *fd* is not open for writing. +:*EFAULT* + The address passed for the path is invalid. +:*EINTR* + The write was interrupted by a *signal*(7) before any data was read. +:*EINVAL* + The file descriptor refers to an object which does not support this operation + or the count specified exceeds *SSIZE\_MAX*. +:*EIO* + An I/O error occurred. +:*ENOSPC* + No space was available to write the new data. +:*EPIPE* + A write to a pipe or socket was attempted when there is no reader. The writing + process will also receive a *SIGPIPE* signal. +## CONFORMING TO +V7, UZI, POSIX.1-2001. +## NOTES +The behaviour of a *write*(2) when passed a count larger than *SSIZE\_MAX* is +undefined by the standards. Fuzix returns *EINVAL* to provide a clear defined +behaviour because on an 8 or 16bit machine it is relatively easy to accidentally +hit this limit. +## SEE ALSO +*lseek*(2), *open*(2), *write*(2), *socket*(4), *tty*(4), *signal*(7) -- 2.34.1