pwrite man page on Tru64

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
Tru64 logo
[printable version]

write(2)							      write(2)

NAME
       write, pwrite, writev - Write to a file

SYNOPSIS
       #include <unistd.h>

       ssize_t write(
	       int filedes,
	       const void *buffer,
	       size_t nbytes ); ssize_t pwrite(
	       int filedes,
	       const void *buffer,
	       size_t nbytes,
	       off_t offset ); #include <sys/uio.h>

       ssize_t writev(
	       int filedes,
	       const struct iovec *iov,
	       int iov_count );

STANDARDS
       Interfaces  documented on this reference page conform to industry stan‐
       dards as follows:

       write(), writev(): XSH4.0, XSH4.2, XSH5.0, XNS5.0

       pwrite(): POSIX.1, XSH5.0

       Unless otherwise stated, when text is tagged with an  indicator	for  a
       particular  revision  of	 a  standard, the information applies when the
       application is built in a compilation environment that adheres  to  the
       specified  and  higher  revisions  of that standard. Refer to the stan‐
       dards(5) reference page for more information about  industry  standards
       and associated tags.

PARAMETERS
       Identifies  the file to which the data is to be written.	 Points to the
       buffer containing the data to be	 written.   Specifies  the  number  of
       bytes  to  write	 to  the  file	associated with the filedes parameter.
       Specifies the desired start position inside the	file  associated  with
       the  filedes  parameter.	 Points to an array of iovec structures, which
       identifies the buffers containing the data to  be  written.  The	 iovec
       structure is defined in the sys/uio.h header file and contains the fol‐
       lowing members:

	      void *iov_base; size_t iov_len; Specifies the  number  of	 iovec
	      structures pointed to by the iov parameter.

DESCRIPTION
       The write() function attempts to write nbytes of data to the file asso‐
       ciated with the filedes parameter from the buffer  pointed  to  by  the
       buffer parameter.

       If  the	nbytes	parameter  is 0 (zero), the write() function returns 0
       (zero) and has no other results if the file is a regular file.

       [XNS5.0]	 If filedes refers to a socket, a write() request  is  equiva‐
       lent to a send() request with no options set.

       The  pwrite() function performs the same action as write(), except that
       it writes into a given position in the file (specified  by  the	offset
       parameter) without changing the file pointer.

       The writev() function performs the same action as the write() function,
       but gathers the output data from the iov_count buffers specified by the
       array  of  iovec structures pointed to by the iov parameter. Each iovec
       entry specifies the base address and length of an area in  memory  from
       which  data  should  be	written.  The  iov_count parameter is valid if
       greater than 0 (zero) and less than  or	equal  to  IOV_MAX,  which  is
       defined	in  the	 <limits.h>  header file. The writev() function always
       writes a complete area before proceeding to the next.

       If filedes refers to a regular file and all of the iov_len  members  in
       the array pointed to by iov are 0 (zero), writev() returns 0 and has no
       other effect.

       With regular files and devices capable of seeking, the  actual  writing
       of  data	 proceeds  from the position in the file indicated by the file
       pointer.	 If this incremented file pointer is greater than  the	length
       of  the	file,  the length of the file is set to this file offset. Upon
       return from the write() or pwrite() function, the file  pointer	incre‐
       ments by the number of bytes actually written.

       If  the	O_SYNC	flag of the file status options is set and the filedes
       parameter refers to a regular file, a successful	 write()  or  pwrite()
       call  does  not	return	until  the data is delivered to the underlying
       hardware, as described in open(2).

       With devices incapable of seeking, writing always takes place  starting
       at  the	current	 position. The value of a file pointer associated with
       such a device is undefined.

       If the O_APPEND flag of the file status options is set, the file offset
       is  set	to the end of the file prior to each write, and no intervening
       file modification operation occurs between changing the file offset and
       the write operation.

       If a write() or pwrite() requests that more bytes be written than there
       is space for (for example, the  ulimit()	 or  the  physical  end	 of  a
       medium),	 only  as  many	 bytes	as there is space for are written. For
       example, suppose there is space for 20 bytes  more  in  a  file	before
       reaching	 a limit. A write of 512 bytes returns 20. The next write of a
       nonzero number of bytes will give a failure  return  (except  as	 noted
       below) and [XSH4.2]   a SIGXFSZ signal is generated for the process.

       If  a write() or pwrite() function is interrupted by a signal before it
       writes any data, it returns -1 with errno set to [EINTR].

       If a write() or pwrite() function is interrupted by a signal  after  it
       successfully writes some data, it returns the number of bytes written.

       After  a	 write()  or  pwrite()	to  a  regular	file  has successfully
       returned: Any successful read() from each byte  position	 in  the  file
       that  was  modified  by	that  write  returns the data specified by the
       write() or pwrite() for that position until  such  byte	positions  are
       again  modified.	  Any subsequent successful write() or pwrite() to the
       same byte position in the file overwrites that file data.

       Write requests to a pipe (or FIFO) are handled the same	as  a  regular
       file  with the following exceptions: There is no file offset associated
       with a pipe; hence each write() or pwrite() request appends to the  end
       of  the	pipe.	If the size of the write() or pwrite() request is less
       than or equal to the value of the PIPE_BUF system variable, the write()
       or  pwrite()  call  is  guaranteed to be atomic. The data is not inter‐
       leaved with data from other processes doing writes on  the  same	 pipe.
       Writes  of  greater  than  PIPE_BUF bytes can have data interleaved, on
       arbitrary boundaries, with writes by other processes,  whether  or  not
       O_NONBLOCK is set.

	      [Tru64  UNIX]  This also applies whether or not O_NDELAY is set.
	      If O_NONBLOCK is clear, a write() or pwrite() request to a  full
	      pipe  causes  the	 process  to  block until enough space becomes
	      available to handle the entire request.

	      [Tru64 UNIX]  This also applies if O_NDELAY is  clear.   If  the
	      O_NONBLOCK flag is set, write() or pwrite() requests are handled
	      differently in the following ways: the function does  block  the
	      process;	requests  for  PIPE_BUF	 or fewer bytes either succeed
	      completely and return nbytes, or return  -1  and	set  errno  to
	      [EAGAIN].	 A  request  for  greater  than	 PIPE_BUF bytes either
	      transfers as much as it can and  returns	the  number  of	 bytes
	      written,	or  transfers no data and returns -1 with errno set to
	      [EAGAIN]. Also, if a request is greater than PIPE_BUF bytes  and
	      all  data	 previously written to the pipe has been read, write()
	      or pwrite() transfers at least PIPE_BUF bytes.

	      [Tru64 UNIX]  This also applies if O_NDELAY is set.

       When attempting to write to a file descriptor (other than a pipe	 or  a
       FIFO)  that  supports nonblocking writes and cannot accept data immedi‐
       ately, the write() and pwrite() functions behave as follows: If	O_NON‐
       BLOCK is clear, the function blocks until the data can be accepted.

	      [Tru64 UNIX]  This also applies if O_NDELAY is clear.  If O_NON‐
	      BLOCK is set, the function does not block the process.  Instead,
	      if  some	data  can  be written without blocking the process, it
	      writes as much as it can and returns the number of  bytes	 writ‐
	      ten.  Otherwise, it returns -1 and errno is set to [EAGAIN].

	      [Tru64  UNIX]  This  also	 applies  if O_NDELAY is set, except 0
	      (zero) is returned.

       [Tru64 UNIX]  When attempting to write to a regular file with  enforce‐
       ment  mode  record  locking enabled and all or part of the region to be
       written is  currently  locked  by  another  process,  the  write()  and
       pwrite()	 functions  behave  as follows: If O_NDELAY and O_NONBLOCK are
       clear (the default), the calling process blocks until all of the block‐
       ing  locks are removed or until the function is terminated by a signal.
       If O_NDELAY or O_NONBLOCK is set, the function  returns	--1  and  sets
       errno to [EAGAIN].

       Upon  successful completion, the write() or pwrite() function marks the
       st_ctime and st_mtime fields of the file for update and, if the file is
       a regular file, clears its set-user ID and set-group ID attributes.

       The  fcntl(2)  reference	 page  provides	 more information about record
       locks.

   Writing Data to STREAMS Files
       [XSH4.2]	 For STREAMS files, the operation of write() and  pwrite()  is
       determined  by  the  values  of	the  minimum  and maximum nbytes range
       (“packet size” accepted by the STREAM). These values are	 contained  in
       the  topmost  STREAM module. Unless the user pushes the topmost module,
       these values cannot be set or tested from user level (see I_PUSH on the
       streamio(7))  reference	page).	If nbytes falls within the packet size
       range, nbytes bytes are written. If nbytes does	not  fall  within  the
       range  and  the	minimum	 packet	 size  value  is  0 (zero), write() or
       pwrite() breaks the buffer into maximum packet size segments  prior  to
       sending the data downstream (the last segment may contain less than the
       maximum packet size).  If nbytes does not fall within the range and the
       minimum	value  is nonzero, write() or pwrite() fails with errno set to
       [ERANGE].  Writing a zero-length buffer (nbytes is  0)  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 the I_SWROPT ioctl() request to enable zero-length messages to be
       sent across the pipe or FIFO.

       [XSH4.2]	  When writing to a STREAM, data messages are created  with  a
       priority	 band of 0 (zero). When writing to a STREAM that is not a pipe
       or FIFO, the write() and	 pwrite()  functions  behave  as  follows:  If
       O_NONBLOCK  is  clear  and  the STREAM cannot accept data (that is, the
       STREAM write queue is full due to internal  flow	 control  conditions),
       the function blocks until data can be accepted.

	      [Tru64 UNIX]  This also applies if O_NDELAY is clear.  If O_NON‐
	      BLOCK is set and the STREAM cannot  accept  data,	 the  function
	      returns -1 and sets errno to [EAGAIN].

	      [Tru64  UNIX]  This  also applies if O_NDELAY is set.  If O_NON‐
	      BLOCK is set and part of the buffer has been written when a con‐
	      dition occurs in which the STREAM cannot accept additional data,
	      the function terminates and returns the number of bytes written.

	      [Tru64 UNIX]  This also applies if O_NDELAY is set.

       [XSH4.2]	 In addition, write(), pwrite(), and writev() will fail if the
       STREAM  head  had  processed  an asynchronous error before the call. In
       this case, the value of errno does not reflect the result  of  write(),
       pwrite(), or writev(), but reflects the prior error.

NOTES
       [Tru64  UNIX]  For  compatibility  with	earlier	 releases,  values for
       iov_len that are greater than or equal to 2^63 will be treated as zero.

       [Tru64 UNIX]  The write(), pwrite(), and writev() functions, which sus‐
       pend  the calling process until the request is completed, are redefined
       so that only the calling thread is suspended.

       [Tru64 UNIX]  When debugging a module that includes the writev()	 func‐
       tion, use _Ewritev to refer to the writev() call.

       When  a	read(), pread(), write(), or pwrite() system call on a pipe is
       interrupted by a signal and no bytes have been transferred through  the
       pipe,  a	 value	of  -1	is  returned and errno is set to [EINTR]. This
       behavior is different from previous releases in which both  read()  and
       write()	either restarted the transfer or set errno to [EINTR], depend‐
       ing on the setting of the SA_RESTART option for the  interrupting  sig‐
       nal.

       As  a  result  of  this change, applications must now either handle the
       [EINTR] error or block any expected signals for	the  duration  of  the
       read(), pread(), write(), or pwrite() operation.

RETURN VALUES
       Upon  successful	 completion,  the write() or pwrite() function returns
       the number of bytes actually written to the file	 associated  with  the
       filedes parameter. This number is never greater than nbytes. Otherwise,
       a value of -1 is returned and errno is set to indicate the error.

       Upon successful completion, the writev() function returns the number of
       bytes that were actually written. Otherwise, a value of -1 is returned,
       the file-pointer remains unchanged, and errno is set  to	 indicate  the
       error.

   End-of-Media Handling for Tapes
       If  writing  goes  beyond  the “early warning” EOT indicator while this
       indicator is disabled, the write(), pwrite(),  and  writev()  functions
       will  return  the  number  of  bytes  actually  written.	 The  write(),
       pwrite(), and writev() functions return a value of -1,  if:  Attempting
       to write past the “real” EOT.  Attempting to write past “early warning”
       EOT indicator while this indicator is enabled.

       Refer to mtio(7) for information on enabling and disabling “early warn‐
       ing” EOT.

   End-of-Media Handling for Disks
       Disk  end-of-media  handling is POSIX-compliant. Attempting to write at
       or beyond the end of a partition returns a value of -1. A partial write
       returns the number of bytes actually written.

       Note: A partial write is a request that spans the end of a partition.

ERRORS
       The  write(),  pwrite(), and writev() functions set errno to the speci‐
       fied values for the following conditions: The O_NONBLOCK flag is set on
       this file and the process would be delayed in the write operation.

	      [Tru64 UNIX]  An attempt was made to write to a STREAM that can‐
	      not accept data with either the O_NDELAY or O_NONBLOCK flag set.

	      [Tru64 UNIX]  An enforcement mode record lock is outstanding  in
	      the  portion  of	the  file  that is to be written.  The filedes
	      parameter does not specify a valid file descriptor that is  open
	      for  writing.  [Tru64 UNIX]  Enforced record locking is enabled,
	      O_NDELAY is clear, and a deadlock condition is detected.	[Tru64
	      UNIX]  The  write	 failed because the user's disk block quota is
	      exhausted.  [Tru64 UNIX]	The buffer parameter or	 part  of  the
	      iov parameter points to a location outside the allocated address
	      space of the process.  An attempt was made to write a file  that
	      exceeds  the maximum file size.  A write() or pwrite() on a pipe
	      is interrupted by a signal and no bytes  have  been  transferred
	      through  the  pipe.   [XSH4.2]  The STREAM or multiplexer refer‐
	      enced by filedes is linked (directly or  indirectly)  downstream
	      from a multiplexer.

	      [XSH4.2]	The  iov_count	parameter value was less than or equal
	      to 0 or greater than IOV_MAX.

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

	      [Tru64  UNIX]  The  file	position  pointer  associated with the
	      filedes parameter was negative.

	      [Tru64 UNIX]  One of the iov_len values in  the  iov  array  was
	      negative	or  the	 sum overflowed a 32-bit integer.  [XSH4.2]  A
	      physical I/O error occurred. These errors do  not	 always	 occur
	      with  the associated function, but can occur with the subsequent
	      function.	 [Tru64 UNIX]  The  file  has  enforcement  mode  file
	      locking  set,  and allocating another locked region would exceed
	      the configurable system  limit  of  NLOCK_RECORD.	  [XSH4.2]  No
	      free space is left on the file system containing the file.

	      [Tru64 UNIX]  An attempt was made to write past the “early warn‐
	      ing” EOT while this indicator was enabled.

	      [Tru64 UNIX]  An attempt was made to write at or beyond the  end
	      of a partition.  [XSH4.2]	 A hangup occurred on the STREAM being
	      written to.

	      The device associated with file descriptor (the filedes  parame‐
	      ter)  is	a  block special device or character special file, and
	      the file pointer is out of range.	 [Tru64 UNIX]  An attempt  was
	      made  to	write to a socket or type SOCK_STREAM that is not con‐
	      nected to a peer socket.	[XSH4.2]  An attempt was made to write
	      to a pipe that has only one end open.

	      An  attempt  was	made  to  write	 to a pipe or FIFO that is not
	      opened for reading by any process. A SIGPIPE signal is  sent  to
	      the  process.   [XSH4.2]	The  transfer request size was outside
	      the range supported by the STREAMS file associated with filedes.

       In addition, the pwrite() function fails and the file  pointer  remains
       unchanged  if  the  following  is true: The file specified by fildes is
       associated with a pipe or FIFO.

       [XSH4.2]	 A write to a STREAMS file can fail if an  error  message  has
       been  received  at  the	STREAM head. In this case, errno is set to the
       value included in the error message.

       For NFS file access, if the write(),  pwrite(),	or  writev()  function
       fails,  errno  may  also	 be set to one of the following values: [Tru64
       UNIX]   For filesystems mounted with  the  nfsv2	 option,  the  process
       attempted  to write beyond the 2 gigabyte boundary.  [Tru64 UNIX]   The
       named file is a	directory  and	write  access  is  requested.	[Tru64
       UNIX]	Insufficient resources, such as buffers, are available to com‐
       plete the call.	Typically, a call used with sockets has failed due  to
       a shortage of message or send/receive buffer space.  [Tru64 UNIX]   The
       named file resides on a read-only  file	system	and  write  access  is
       required.   [Tru64 UNIX]	  The NFS file handle is stale. An opened file
       was deleted by the server or another client, a  client  cannot  open  a
       file  because  the server has unmounted or unexported the remote direc‐
       tory, or	 the  directory	 that  contains	 an  opened  file  was	either
       unmounted or unexported by the server.

       If  the write(), pwrite(), or writev() function fails while in the Sys‐
       tem V habitat, errno may also be set to one of  the  following  errors:
       [Tru64  UNIX]	A  write to a pipe (FIFO) of PIPE_BUF bytes or less is
       requested, O_NONBLOCK is set, and less than nbytes bytes of free	 space
       is available.

	      [Tru64  UNIX]  Enforced  record locking was enabled, O_NDELAY or
	      O_NONBLOCK was set and there were record-locks on the  file,  or
	      O_NONBLOCK  was  set,  and  data cannot be accepted immediately.
	      [Tru64 UNIX]   The sum of the iov_len values in  the  iov	 array
	      overflowed  an  integer.	 [Tru64 UNIX]	Attempts to write to a
	      STREAM with nbytes are outside the specified minimum and maximum
	      range, and the minimum value is non-zero.

SEE ALSO
       Functions:  fcntl(2),  getmsg(2),  lseek(2), open(2), pipe(2), poll(2),
       select(2), lockf(3), ulimit(3)

       Files: mtio(7)

       Standards: standards(5)

								      write(2)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server Tru64

List of man pages available for Tru64

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net