Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
write(2)		      System Calls Manual		      write(2)

NAME
       write, writev, pwrite - write on	a file

SYNOPSIS
DESCRIPTION
       The  function  attempts to write	nbyte bytes from the buffer pointed to
       by buf to the file associated with the open file	descriptor, fildes.

       If nbyte	is 0, will return 0 and	have no	other results if the file is a
       regular file; otherwise,	the results are	unspecified.

       On  a regular file or other file	capable	of seeking, the	actual writing
       of data proceeds	from the position in the file indicated	 by  the  file
       offset  associated with fildes.	Before successful return from 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	flag of	the file status	flags is set and fildes	refers
       to a regular file, a successful does not	return until the data  is  de-
       livered	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	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 write operation.

       If a requests that more bytes be	written	than there is  room  for  (for
       example,	 the  ulimit  or  the  physical	end of a medium), only as many
       bytes as	there is room for 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. The	next write of  a  non-zero  number  of
       bytes will give a failure return	(except	as noted below)	and the	imple-
       mentation will generate a signal	for the	process.

       If is interrupted by a signal before it writes any data,	it will	return
       -1 with set to

       If  is  interrupted by a	signal after it	successfully writes some data,
       it will return the number of bytes written.

       If the value of nbyte is	greater	than the result	is  implementation-de-
       pendent.

       After a to a regular file has successfully returned:

	      o	 Any  successful  from each byte position in the file that was
		 modified by that write	will return the	data specified by  the
		 for  that  position until such	byte positions are again modi-
		 fied.

	      o	 Any subsequent	successful 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:

	      o	 There is no file offset associated with a  pipe,  hence  each
		 write request will append to the end of the pipe.

	      o	 Write	requests of bytes or less will not be interleaved with
		 data from other processes doing  writes  on  the  same	 pipe.
		 Writes	 of  greater  than bytes may have data interleaved, on
		 arbitrary boundaries, with writes by other processes, whether
		 or not	the flag of the	file status flags is set.

	      o	 If  the  flag is clear, a write request may cause the process
		 to block, but on normal completion it will return nbyte.

	      o	 If the	flag is	set, requests will  be	 handled  differently,
		 in the	following ways:

		 -  The	function will not block	the process.

		 -  A  write request for or fewer bytes	 will have the follow-
		    ing	effect:	 If there is sufficient	space available	in the
		    pipe,  will	transfer all the data and return the number of
		    bytes  requested.  Otherwise, will transfer	 no  data  and
		    return -1 with set to

		 -  A  write  request for more than bytes will case one	of the
		    following:

		    a. When at least one byte can be written, transfer what it
		       can  and	 return	the number of bytes  written. When all
		       data previously written to the pipe is  read,  it  will
		       transfer	at least bytes.

		    b. When  no	 data can be written, transfer no data and re-
		       turn -1 with set	to

       When attempting to write	to a file descriptor (other  than  a  pipe  or
       FIFO)  that supports non-blocking writes	and cannot accept the data im-
       mediately:

	      o	 If the	flag is	clear, will block until	the data  can  be  ac-
		 cepted.

	      o	 If  the flag is set, will not block the process. If some data
		 can be	written	without	blocking the process, will write  what
		 it  can and return the	number of bytes	written. Otherwise, it
		 will return -1	and will be set	to

       Upon successful completion, where is greater than 0, will mark for  up-
       date the	st_ctime and st_mtime fields of	the file, and if the file is a
       regular file, the and bits of the file mode may be cleared.

       If fildes refers	to a STREAM, the operation of  is  determined  by  the
       values  of the minimum and maximum nbyte	range ("packet size") accepted
       by the STREAM. These values are determined by the topmost  STREAM  mod-
       ule.  If	 nbyte falls within the	packet size range, nbyte bytes will be
       written.	If nbyte does not fall within the range	and the	minimum	packet
       size  value  is	0, will	break the buffer into maximum packet size seg-
       ments prior to sending the data downstream (the last segment  may  con-
       tain  less than the maximum packet size). If nbyte does not fall	within
       the range and the minimum value is non-zero,  will  fail	 with  set  to
       Writing	a zero-length buffer ( nbyte is	0) to a	STREAMS	device sends 0
       bytes with 0 returned. However,	writing	 a  zero-length	 buffer	 to  a
       STREAMS-based  pipe  or	FIFO  sends  no	message	and 0 is returned. The
       process may issue to enable zero-length messages	to be sent across  the
       pipe or FIFO.

       When  writing  to  a STREAM, data messages are  created with a priority
       band of 0.  When	writing	to a STREAM that is not	a pipe or FIFO:

	      o	 If is clear, and the cannot accept data (the write  queue  is
		 full  due  to	internal flow control  conditions), will block
		 until data can	be accepted.

	      o	 If is set and the cannot accept data, will return -1 and  set
		 to

	      o	 If  is	 set  and  part	of the buffer has been written while a
		 condition in which the	cannot accept additional data  occurs,
		 will terminate	and return the number of bytes written.

       In  addition,  and  will	fail if	the head had processed an asynchronous
       error before the	call. In this case, the	value of does not reflect  the
       result of or but	reflects the prior error.

       The  function  is  equivalent  to  but gathers the output data from the
       iovcnt buffers specified	by the	members	 of  the  iov  array:  iov[0],
       iov[1], ..., iov[iovcnt-1].  iovcnt is valid if greater than 0 and less
       than or equal to	defined	in

       Each iovec entry	specifies the base address and length of  an  area  in
       memory  from  which  data  should  be written. The function will	always
       write a complete	area before proceeding to the next.

       If fildes refers	to a regular file and all of the  iov_len  members  in
       the  array pointed to by	iov are	0, will	return 0 and have no other ef-
       fect.  For other	file types, the	behaviour is unspecified.

       If the sum of the iov_len values	is greater than	 the  operation	 fails
       and no data is transferred.

       The  function  performs the same	action as except that it writes	into a
       given position without changing the file	pointer.  The first three  ar-
       guments	to are the same	as with	the addition of	a fourth argument off-
       set for the desired position inside the file.

RETURN VALUE
       Upon successful completion, and will return the number of  bytes	 actu-
       ally  written  to  the  file  associated	with fildes.  This number will
       never be	greater	than nbyte.  Otherwise,	-1 is returned and is  set  to
       indicate	the error.

       Upon successful	completion, returns the	number of bytes	actually writ-
       ten. Otherwise, it returns a value of -1, the file-pointer remains  un-
       changed,	and is set to indicate an error.

ERRORS
       The and functions will fail if:

	      [EAGAIN]	     The  flag	is set for the file descriptor and the
			     process would be delayed in the operation.

	      [EBADF]	     The fildes	argument is not	a valid	file  descrip-
			     tor open for writing.

	      [EFBIG]	     An	 attempt was made to write a file that exceeds
			     the implementation-dependent maximum file size or
			     the process' file size limit.

	      [EINTR]	     The write operation was terminated	due to the re-
			     ceipt of a	signal,	and no data was	transferred.

	      [EIO]	     A physical	I/O error has occurred.

	      [EIO]	     The process is a member of	a  background  process
			     group attempting to write to its controlling ter-
			     minal, is set, the	process	 is  neither  ignoring
			     nor blocking and the process group	of the process
			     is	orphaned. This error may also be returned  un-
			     der implementation-dependent conditions.

	      [ENOSPC]	     There  was	 no free space remaining on the	device
			     containing	the file.

	      [EPIPE]	     An	attempt	is made	to write to  a	pipe  or  FIFO
			     that  is  not open	for reading by any process, or
			     that only has one end open. A signal will also be
			     sent to the process.

	      [ERANGE]	     The  transfer  request size was outside the range
			     supported by the file associated with fildes.

       The function will fail if:

	      [EINVAL]	     The sum of	the iov_len values in  the  iov	 array
			     would overflow an ssize_t.

       The and functions may fail if:

	      [EINVAL]	     The or multiplexer	referenced by fildes is	linked
			     (directly or indirectly) downstream from a	multi-
			     plexer.

	      [ENXIO]	     A	request	 was made of a non-existent device, or
			     the request was outside the capabilities  of  the
			     device.

	      [ENXIO]	     A	hangup	occurred  on  the being	written	to.

       A write to a file may fail if an	error message has been received	at the
       head. In	this case, is set to the value included	in the error message.

       The function may	fail and set to:

	      [EINVAL]	     The iovcnt	argument was less than or equal	to  0,
			     or	greater	than

       The function fails and the file pointer remains unchanged if:

	      [EINVAL]	     The offset	argument is invalid, The value is neg-
			     ative.  [ESPIPE] fildes is	associated with	a pipe
			     or	FIFO.

SEE ALSO
       chmod(2),  creat(2), dup(2), fcntl(2), getrlimit(2), lseek(2), open(2),
       pipe(2),	ulimit(2), <limits.h>, <stropts.h>, <sys/uio.h>, <unistd.h>.

CHANGE HISTORY
       First released in Issue 1.

       Derived from Issue 1 of the SVID.

Issue 4
       The following changes are  incorporated	for  alignment	with  the  ISO
       POSIX-1 standard:

	      o	 The  type of the argument buf is changed from char * to const
		 void*,	and the	type of	the argument byte is changed from  un-
		 signed	size_t.

	      o	 The DESCRIPTION section is changed:

		 -  to indicate	that writing at	end-of-file is atomic

		 -  to	identify  that	is  now	 used to determine the maximum
		    value of nbyte

		 -  to indicate	the consequences of activities after a call to
		    the	function

		 -  To	improve	 clarity,  the	text  describing operations on
		    pipes or FIFOs when	is set is restructured.

       Other changes are incorporated as follows:

	      o	 The header is added to	the SYNOPSIS section.

	      o	 Reference to ulimit in	the DESCRIPTION	section	is  marked  as
		 an extension.

	      o	 Reference  to	the  process' file size	limit and the function
		 are marked as extensions in the description of	the error.

	      o	 The error is marked as	an extension.

	      o	 The APPLICATION USAGE section is removed.

	      o	 The description of is amended.

Issue 4, Version 2
       The following changes are incorporated for X/OPEN UNIX conformance:

	      o	 The function is added to the SYNOPSIS.

	      o	 The DESCRIPTION is updated to describe	the  reading  of  data
		 from files, an	operational description	of the function	is in-
		 cluded, and a statement is added indicating that will be gen-
		 erated	 if an attempted write operation would cause the maxi-
		 mum file size to be exceeded.

	      o	 The RETURN VALUE section is updated to	 describe  values  re-
		 turned	by the function.

	      o	 The  ERRORS  section has been restructured to describe	errors
		 that apply to both and	writev() apart from those  that	 apply
		 to specifically. The and errors are also added.

write(2)		      System Calls Manual		      write(2)

				  HP-UX	EXTENSIONS

DESCRIPTION
       The structure is	defined	in

       For  ordinary files, if the file	status flag is set, the	write does not
       return until both the file data and the file attributes required	to re-
       trieve the data are physically updated.	If the flag is set, the	behav-
       ior is identical	to that	for with the addition that all file attributes
       changed	by  the	 write	operation (including access time, modification
       time and	status change time) are	also physically	updated	prior  to  re-
       turning to the calling process.

       For  block special files, if the	or the flag is set, the	write does not
       return until the	data is	physically updated.  How the data reaches  the
       physical	media is implementation- and hardware-dependent.

       A  write	 to an ordinary	file is	prevented if enforcement-mode file and
       record locking is set, and another process owns a lock on  the  segment
       of the file being written:

	      If or is set, the	write returns -1 and sets to

	      If and are clear,	the write does not complete until the blocking
	      record lock is removed.

       If the file being written is a pipe  (or	 FIFO),	 the  system-dependent
       maximum	number	of bytes that it can store is given by (defined	in The
       minimum value of	on any HP-UX system is 8192.  When writing a pipe, the
       following conditions apply:

	      If the or	file status flag is set:

	      If  nbyte	is less	than or	equal to and sufficient	room exists in
	      the pipe or the succeeds and returns the number of  bytes	 writ-
	      ten;

	      If  nbyte	 is less than or equal to but insufficient room	exists
	      in the pipe or the returns having	written	nothing.  If  is  set,
	      is returned and is set to	[EAGAIN].  If is set, is returned.

	      If nbyte is greater than and the pipe or FIFO is full, the write
	      returns having written nothing.  If is set, is returned  and  is
	      set to [EAGAIN].	If is set, is returned.

	      If  nbyte	 is  greater  than and some room exists	in the pipe or
	      FIFO, as much data as fits in the	pipe or	FIFO is	 written,  and
	      returns  the  number  of	bytes actually written,	an amount less
	      than the number of bytes requested.

	      If the and file status flags are clear:

	      The always executes correctly (blocking as necessary),  and  re-
	      turns the	number of bytes	written.

       For  character special devices, if the call was used on the same	device
       after it	was opened, returns sets to [EBADF], and issues	the signal  to
       the process.

       clears the and privilege	vectors	on the file.

       If  the	write  is performed by any user	other than the owner or	a user
       who has appropriate privileges, clears the  set-user-ID,	 set-group-ID,
       and  sticky  bits on all	nondirectory files.  If	the write is performed
       by the owner or a user who has appropriate privileges, the behavior  is
       file-system dependent.  In some file systems, the write clears the set-
       user-ID,	set-group-ID, and sticky bits  on  a  nondirectory  file.   In
       other  file systems, the	write does not clear these bits	on a nondirec-
       tory file.

       For directories,	does not  clear	 the  set-user-ID,  set-group-ID,  and
       sticky bits.

ERRORS
       If or fails, the	file offset remains unchanged and is set to one	of the
       following values.

	      [EAGAIN]	     Enforcement-mode file and record locking was set,
			     was set, and there	was a blocking record lock.

	      [EDEADLK]	     A	resource  deadlock  would occur	as a result of
			     this operation (see lockf(2) and fcntl(2)).

	      [EDQUOT]	     User's disk quota block limit  has	 been  reached
			     for this file system.

	      [EFBIG]	     The  file	is a regular file and nbyte is greater
			     than zero and the starting	 position  is  greater
			     than  or  equal to	the offset maximum established
			     in	the  open  file	 description  associated  with
			     fildes.

	      [ENOLCK]	     The  system record	lock table is full, preventing
			     the write from sleeping until the blocking	record
			     lock is removed.

	      [ENOSPC]	     Not enough	space on the file system.  The process
			     does not possess the effective privilege to over-
			     ride this restriction.

       If  fails,  the	file offset remains unchanged and is set to one	of the
       following values:

	      [EFAULT]	     iov_base or iov points outside of	the  allocated
			     address  space.   The  reliable detection of this
			     error is implementation dependent.

	      [EINVAL]	     One of the	iov_len	values in  the	iov  array  is
			     negative.

       If  or  fails, the file offset is updated to reflect the	amount of data
       transferred and is set to one of	the following values.

	      [EFAULT]	     buf points	outside	the  process's	allocated  ad-
			     dress  space.  The	reliable detection of this er-
			     ror is implementation dependent.

EXAMPLES
       Assuming	a process opened a file	for writing, the following call	to at-
       tempts  to  write  mybufsize bytes to the file from the buffer to which
       mybuf points.

WARNINGS
       Check signal(5) for the appropriateness of signal references on systems
       that  support (see sigvector(2)).  can affect the behavior described on
       this page.

       Character special devices, and raw  disks  in  particular,  apply  con-
       straints	on how can be used.  See specific Section 7 manual entries for
       details on particular devices.

AUTHOR
       was developed by	HP, AT&T, and the University of	California, Berkeley.

SEE ALSO
       mkfs(1M)	 creat(2),  dup(2),  fcntl(2),	lockf(2),  lseek(2),  open(2),
       pipe(2),	sigvector(2), ulimit(2), ustat(2), signal(5).

STANDARDS CONFORMANCE
								      write(2)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | SEE ALSO | CHANGE HISTORY | Issue 4 | Issue 4, Version 2 | DESCRIPTION | ERRORS | EXAMPLES | WARNINGS | AUTHOR | SEE ALSO | STANDARDS CONFORMANCE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=write&sektion=2&manpath=HP-UX+11.22>

home | help