NXWrite

Atomically positions the file pointer and writes to the specified file.

Library:LibC
Classification:NKS
Service:File and Directory I/O

Syntax

  #include <nks/fsio.h>
  
  int NXWrite (
     NXHandle_t      handle, 
     NXOffset_t      offset, 
     size_t          length, 
     const void     *address,
     unsigned long   flags, 
     size_t         *bytesWritten);

Parameters

handle

(IN) Specifies a file handle (or descriptor), which refers to a system-maintained state description for a file and was obtained from calling a create or open function. If a FIFO or other sequential I/O device is specified, all values that might be in offset are ignored.

offset

(IN) Specifies the starting offset for writing to the file.

length

(IN) Specifies the number of bytes to be written. If zero, NXWrite returns zero and has no other results. If the value is greater than NX_MAX_FILESIZE, the result is undefined.

address

(IN) Points to the memory address, which is meaningful in your virtual machine, where the data to be written should be placed.

flags

(IN) Pass 0.

bytesWritten

(OUT) Points to the number of bytes actually written. On failure, returns -1.

Return Values

If successful, returns 0, and in bytesWritten, a non-negative integer indicating the number of bytes actually written. Otherwise, returns one of the following error codes.

Decimal

Hex

Constant

Description

4

0x04

NX_EBADF

The handle is not a valid file handle or descriptor open for writing.

9

0x09

NX_EINVAL

The offset is invalid.

12

0x0C

NX_ENOSPC

During NXWrite, there is no free space left on the device.

24

0x18

NX_EAGAIN

Resource exhaustion prevents successful completion of the call at this time. For non-blocking FIFOs, this means that no buffer space is available.

28

0x1C

NX_EIO

A physical I/O error has occurred. This can indicate either a failure to write to a local volume or failure of connection to a remote file volume link.

71

0x47

NX_EFBIG

The NXWrite call attempted to extend the size of the file beyond system specified limits.

105

0x69

NX_ENOCONTEXT

The calling thread has no NKS context.

Remarks

NXWrite attempts to write the specified number of bytes from the specified buffer to the file associated with the file handle.

If more bytes than there are room for are requested to be written (for example, if the write would exceed the system file size limit or the free space on the device), only the bytes that there are room for will be written. For example suppose there is space for 20 more bytes before reaching a limit. A write of 512 bytes returns 20. The next write of a nonzero number of bytes will fail and the file size is set to the length at which the write operation ended.

An NXWrite operation also updates the modification time and the time of the last status change.

See Also