From: Alan Cox Date: Sat, 24 Sep 2016 13:19:01 +0000 (+0100) Subject: man2: add a couple more entries X-Git-Url: https://git.ndcode.org/public/gitweb.cgi?a=commitdiff_plain;h=7e20d9e48dc2cb1c14fce8c6aad6958750fbdcd4;p=FUZIX.git man2: add a couple more entries One by one... --- diff --git a/Applications/man2/mknod.2 b/Applications/man2/mknod.2 index 795264ae..f50e7c1a 100644 --- a/Applications/man2/mknod.2 +++ b/Applications/man2/mknod.2 @@ -1 +1,79 @@ - \ No newline at end of file +MKNOD(2) +## NAME +mknod - create a special file +## SYNOPSIS +*#include *\ + +*#include *\ + +*#include *\ + +*#include * + +*int mknod*(*const char \**path, *mode\_t* mode, *dev_t* dev); +## DESCRIPTION +The *mknod*() call creates a filesystem node at the location given by +*path*, including special nodes for devices as well as *fifo*(7) nodes. + +The *mode* specifies both the file permissions to be used (along with the +*umask*(2) of the process) to create the node, and also specifies the type +of node to create. + +The *dev* node specifies the device number of the device as computed by +*makedev*(3) from the major and minor number of the device. The *dev* node is +ignored for non device files. + +The following node types are permitted + +:*S\_IFBLK* + A block device representing mountable storage. +:*S\_IFCHR* + A character device. +:*S\_IFDIR* + A directory node. This creates a blank directory node. It is not the same as + *mkdir*(2) and should only be used for specialist purposes. +:*S\_IFIFO* + A *fifo*(7) node (often called a 'named pipe'). +:*S\_IFREG* + An empty regular file. + +A normal user is only permitted to use this call to create *fifo* nodes. The +superuser may create any type of node desired. +## RETURN VALUE +On success, zero is returned. On error -1 is returned and errno is set. +## ERRORS +:*EACCES* + The caller has insufficient rights to access the path specified or to + create the new entry. +:*EEXIST* + The node specified by *path* already exists. +:*EFAULT* + The address passed for the path is invalid. +:*EINVAL* + The node type specified is invalid or unsupported. +:*EIO* + An I/O error occurred. +:*ENOENT* + A directory component of the path does not exist. +:*ENOMEM* + No memory was available. +:*ENOSPC* + The filesystem does not have sufficient room to create the new node. +:*EPERM* + An attempt was made to create a node other than a *fifo* and the caller is + not superuser. +:*EROFS* + The file system is read-only. +## CONFORMING TO +V7, UZI, POSIX.1-2001 +## NOTES +Historic Unix used this call and a privileged binary in order to create +directories. The *mkdir*(2) call shoudl be used instead. + +POSIX only defines the behaviour of this function for *S_FIFO*. The *mkfifo*(3) +function should be used in preference. + +Fuzix allows the superuser to create any node type. This power should be used +with great care. +## SEE ALSO +*mkdir*(2), *umask*(2), *makedev*(3), *mkfifo*(3), *fifo*(7) diff --git a/Applications/man2/read.2 b/Applications/man2/read.2 new file mode 100644 index 00000000..1c4a7f3f --- /dev/null +++ b/Applications/man2/read.2 @@ -0,0 +1,53 @@ +READ(2) +## NAME +read - read data from a file descriptor +## SYNOPSIS +*#include * + +*ssize\_t read*(*int* fd, *void* \*buf, *size\_t* count); +## DESCRIPTION +The *read*() call reads up to the specified *count* of bytes into the buffer +*buf*. + +On files that support seeking the read begins at the current file offset and +the file offset is incremented by the number of bytes read. A read will not +continue beyond the current end of file, and if no bytes can be read 0 will be +returned to indicate end of file. + +If the count is zero then zero will be returned. If the count is larger than +*SSIZE\_MAX* an error will be returned. + +A read from a device such as a *socket*(4), *tty*(4) or *fifo*(7) may block and +wait for data. This behaviour is controlled by the *O\_NDELAY* flag when opening +the file. Waiting read calls may also be interrupted by a *signal*(7). +## RETURN VALUE +On success, the number of bytes successfully read is returned. If no data could +be read due to an error then -1 is returned and errno is set. +## ERRORS +:*EAGAIN* + The read would block but the *O\_NDELAY* flag is set on the file descriptor. +:*EBADF* + The file descriptor *fd* is not open for reading. +:*EFAULT* + The address passed for the path is invalid. +:*EINTR* + The read 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. +## CONFORMING TO +V7, UZI, POSIX.1-2001. +## NOTES +The behaviour of a *read*(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. + +Fuzix permits a directory node to be read, and internally implements *readdir*(3) +this way. Future Fuzix on larger machines may support multiple file system types and if so +the ability to read from a directory will be removed from those platforms in favour of +new system calls. Portable application code should always use *readdir*(3). +## SEE ALSO +*lseek*(2), *open*(2), *write*(2), *readdir*(3), *socket*(4), *tty*(4), *signal*(7)