write - write bytes to file

Syntax	#include <unistd.h> BS2000 #include <stdio.h> (End) ssize_t write(int fildes, const void *buf, size_t nbyte);
Description	scription write() attempts to write nbyte bytes from the buffer pointed to by buf to the file associated with the file descriptor fildes. BS2000 SAM files are always processed as text files with elementary functions. (End) On a file that is capable of seeking, the actual write operation proceeds from the position in the file indicated by the file offset (i.e. the file position indicator) associated with fildes. Before a successful return from write(), the file offset is incremented by the number of bytes actually written. On a regular file, if this incremented file offset is greater than the length of the file, the length of the file will be set to this file offset. If the O_SYNC flag of the file status flags is set and fildes refers to a regular file, a successful write() does not return until the data is delivered to the underlying hardware. On a file not capable of seeking, writing always takes place starting at the current position. The value of a file offset associated with such a device is undefined. If the O_APPEND flag of the file status flags is set, the file offset will be set to the end of the file prior to each write and no intervening file modification operation will occur between changing the file offset and the beginning of the write() operation. If a write() requests that more bytes be written than the amount of available space (because of the ulimit() or the physical end of a medium, for instance), only as many bytes as can be accommodated will be written. For example, suppose there is space for 20 bytes more in a file before reaching a limit. A write of 512 bytes will return 20 in this case, and the next write with a non-zero number of bytes will return with an error (except in the cases noted below) and will sent the SIGXFSZ signal to the process. If write() is interrupted by a signal before it has written the data, -1 is returned and errno is set to EINTR. If write() is interrupted by a signal after it successfully writes some data, it will return the number of bytes written. The following applies following a successful write() to a regular file: Any successful read() from each byte position in the file that was modified by that write will return the data specified by the write() for that position until such byte positions are again modified. Any subsequent successful write() to the same byte position in the file will overwrite that file data. Write requests to a pipe or FIFO will be handled the same as a regular file, with the following exceptions: There is no file offset associated with a pipe, so each write request will append to the end of the pipe. Write requests of {PIPE_BUF} bytes or less bytes will not be interleaved with data from other processes doing writes on the same file. Writes of greater than {PIPE_BUF} bytes may have data interleaved, on arbitrary boundaries, with writes by other processes, whether or not the O_NONBLOCK flag in the system file status byte is set. If the O_NONBLOCK flag is clear, a write request may cause the process to block, but on normal completion it will return nbyte. If the O_NONBLOCK flag is set, write() requests will be handled differently, in the following ways: write() will not block the process. A write request for {PIPE_BUF} or fewer bytes will have the following effects: If there is sufficient space available in the pipe, write() will transfer all the data and return the number of bytes requested. If there is not enough space available in the pipe, write() will transfer no data and return -1 with errno set to EAGAIN. A write request for more than {PIPE_BUF} bytes will cause one of the following: When at least one byte can be written, write() will transfer as many bytes as it can and return the number of bytes written. When all data previously written to the pipe is read, it will transfer at least {PIPE_BUF} bytes. When no data can be written, write() will transfer no data and return -1 with errno set to EAGAIN. If a request is for more than {PIPE_BUF} bytes and all data previously written to the file has been read, write() will transfer at least {PIPE_BUF} bytes. The following occurs when attempting to write to a file descriptor (other than a pipe or FIFO) that supports non-blocking writes: If the O_NONBLOCK flag is clear, write() will block until the data can be accepted. If the O_NONBLOCK flag is set, write() will not block the process. If some data can be written without blocking the process, write() will write as many bytes as it can and return the number of bytes written. Otherwise, it will return -1 and errno will be set to EAGAIN. Upon successful completion, where nbyte is greater than 0, write() will mark for update the st_ctime and st_mtime structure components of the file. The S_ISUID and S_ISGID bits of the file mode will be cleared if the process does not have appropriate privileges. If fildes describes a STREAM, the write operation is determined by the minimum and maximum values for nbyte („packet size“) accepted by the STREAM. These values are defined by the highest level STREAM module. If nbyte bytes is the permitted packet size, nbyte bytes are written. If nbyte is in the permitted range for the packet size and the smallest packet size is equal to 0, write() divides the buffer up into segments of a size equal to the maximum packet size before the data is sent upstream (the last segment can be smaller). If nbyte is not in the permitted range for the packet size and the smallest packet size is not equal to 0, write() fails and sets errno to ERANGE. If a buffer of length 0 (nbyte = 0) is written to a STREAM, write() sends a message of length 0 and returns the value 0. However, if a buffer of length 0 is written to a STREAM-based pipe or a FIFO file, nothing is sent and 0 is returned. The process can use I_SWROPT ioctl() if messages of length 0 are to be sent through the pipe or FIFO file. If write() writes to a STREAM, messages with the priority class 0 are generated. The following rules apply if write() writes to a STREAM that is not a pipe or a FIFO file: If the O_NONBLOCK flag is clear and the STREAM does not accept any data (because the STREAM write queue is full due to internal control flow conditions), write() blocks until the data is accepted. If the O_NONBLOCK flag is set and the STREAM does not accept any data, write() fails, returns -1 and sets errno to EAGAIN. If the O_NONBLOCK flag is set and write() has already written a portion of the buffer when a condition arises in which the STREAM does not accept any more data, write() terminates and returns the number of bytes actually written. If threads are used, the function affects the process or a thread in the following manner: Write bytes to file A write request for a pipe or FIFO is handled just like such a request for a normal file with the following exceptions: If the O_NONBLOCK flag is clear, a write request can block the thread, but returns the result nbyte if it terminates normally. If the O_NONBLOCK flag is set, the request from write() is handled differently: write() does not block the thread. If an attempt is made to write to a file descriptor that is not a pipe or FIFO and supports non-blocking writes, the following occurs: If the O_NONBLOCK flag is clear, write() blocks the calling thread until the data is accepted. EAGAIN - the O_NONBLOCK flag is set for the file descriptor and the thread would be stopped by the write operation. Furthermore, if an EPIPE error occurs, then SIGPIPE signal is not sent to the process, but to the calling thread instead.
Return val.	Number of bytes actually written
		upon successful completion. This number will never be greater than nbyte.
	0	if data was to be written to a regular file and nbyte is equal to 0. No data will be written.
	-1	if an error occurs. write() will not have written any data due to one of the following errors: A physical I/O error occurred. fildes is not a valid file descriptor. The file does not exist. No write permission exists for the file. The area containing the data was not correctly specified. errno is set to indicate the error.
Errors	write() fails if the following applies:
	EAGAIN	The O_NONBLOCK flag is set for the file descriptor and the process would be delayed in the write() operation.
	EBADF	fildes is not a valid file descriptor open for writing.
	EFBIG	An attempt was made to write a file that exceeds the maximum possible file size or the process file size limit (see getrlimit() and ulimit()).
	Extension
	EAGAIN	The amount of system memory available for raw I/O is temporarily insufficient or an attempt was made to write to a stream that cannot accept data with the O_NDELAY or O_NONBLOCK flag set or an attempt was made to write {PIPE_BUF}or fewer bytes to a pipe or FIFO and less than nbytes of free space was available. (End)
	Extension
	EDEADLK	The write() function is sleeping and causes a deadlock situation to occur.
	EFAULT	buf points outside the allocated address space of the process. (End)
	EINTR	The write operation was terminated by a signal, and no data was transferred.
	Extension
	EINVAL	An attempt was made to write to a stream associated with a multiplexer. (End)
	EIO	A physical I/O error has occurred, or the process is in a background process group and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the SIGTTIN signal or the process group of the process is orphaned.
	ENOSPC	There was no free space remaining on the device containing the file.
	Extension
	ENOSR	An attempt was made to write to a stream for which not enough space is available. (End)
	ENXIO	A request was made of a non-existent device, or the request was outside the capabilities of the device.
	EPIPE	An attempt was made to access a non-existent device, or the request was outside the capabilities of the device. The process gets a SIGPIPE signal.
	ERANGE	An attempt was made to write to a stream with an mbyte value outside the prescribed minimum and maximum limits, and the minimum value is non-zero.
	EINVAL	The stream or multiplexer referred to by fildes is directly or indirectly connected via a multiplexer downstream.
	ENXIO	An attempt was made to access a non-existent device or the device was not capable of the request.
	ENXIO	A hang-up occurred during writing to the stream.
	write() will also fail if an asynchronous error message appears at the STREAM head before the call. In this case, the value of errno does not refer to write() but to the previous STREAM error.
Notes	The sizeof() function should be used to ensure that the value specified in nbyte does not exceed the size of the buffer. BS2000 The number of bytes actually written should be verified after each call to write(): If the result is less than the value specified in nbyte, it generally means that an error has occurred. If the result is greater than the nbyte specification, tab characters (\t) were written to a text file; these tab characters were expanded to the appropriate spaces and included in the number of bytes returned. The bytes are not written immediately to the external file but are stored in an internal C buffer (see section “Buffering streams”). Control characters for white space (\n, \t, etc.) are converted to their appropriate effect when output to text files, depending on the type of text file (see section “White-spacecharacters”). (End) The following applies in the case of text files with SAM access mode and variable record length for which a maximum record length is also specified: When the O_NOSPLIT specification was entered for open, records which are longer than the maximum record length are truncated to the maximum record length when they are written with write. By default (i.e. without the specification O_NOSPLIT), these records are split into multiple records. If a record has precisely the maximum record length, a record of the length zero is written after it. (End)
See also	creat(), dup(), fcntl(), lseek(), open(), pipe(), ulimit(), unistd.h.