Italian Translation Report: Node.js [Part 49 - 1320 words]

The module provides an API for interacting with the file system in a manner closely modeled around standard POSIX functions.
To use this module:
All file system operations have synchronous and asynchronous forms.
The asynchronous form always takes a completion callback as its last argument. The arguments passed to the completion callback depend on the method, but the first argument is always reserved for an exception. If the operation was completed successfully, then the first argument will be or
Exceptions that occur using synchronous operations are thrown immediately and may be handled using, or may be allowed to bubble up.
handle the error
Note that there is no guaranteed ordering when using asynchronous methods. So the following is prone to error because the operation may complete before the operation
To correctly order the operations, move the call into the callback of the operation:
In busy processes, the programmer is strongly encouraged to use the asynchronous versions of these calls. The synchronous versions will block the entire process until they complete — halting all connections.
While it is not recommended, most fs functions allow the callback argument to be omitted, in which case a default callback is used that rethrows errors. To get a trace to the original call site, set the environment variable:
Omitting the callback function on asynchronous fs functions is deprecated and may result in an error being thrown in the future.
File paths
Most operations accept filepaths that may be specified in the form of a string, a, or a object using the protocol.
String form paths are interpreted as UTF-8 character sequences identifying the absolute or relative filename.
Relative paths will be resolved relative to the current working directory as specified by
Example using an absolute path on POSIX:
Example using a relative path on POSIX (relative to
Paths specified using a are useful primarily on certain POSIX operating systems that treat file paths as opaque byte sequences.
On such systems, it is possible for a single file path to contain sub-sequences that use multiple character encodings.
As with string paths, paths may be relative or absolute:
Note: On Windows Node.js follows the concept of per-drive working directory. This behavior can be observed when using a drive path without a backslash.
For example can potentially return a different result than
For more information, see this MSDN page.
URL object support
For most module functions, the or argument may be passed as a object.
Only objects using the protocol are supported.
URLs are always absolute paths.
Using objects might introduce platform-specific behaviors.
On Windows, URLs with a hostname convert to UNC paths, while URLs with drive letters convert to local absolute paths.
URLs without a hostname nor a drive letter will result in a throw:
On Windows
with hostname convert to UNC path
with drive letters convert to absolute path
without hostname must have a drive letters
File URL path must be absolute
URLs with drive letters must use as a separator just after the drive letter.
Using another separator will result in a throw.
On all other platforms, URLs with a hostname are unsupported and will result in a throw:
On other platforms:
with hostname are unsupported
must be absolute
convert to absolute path
A URL having encoded slash characters will result in a throw on all platforms:
File URL path must not include encoded or characters
On POSIX
On Windows, URLs having encoded backslash will result in a throw:
File Descriptors
On POSIX systems, for every process, the kernel maintains a table of currently open files and resources. Each open file is assigned a simple numeric identifier called a file descriptor. At the system-level, all file system operations use these file descriptors to identify and track each specific file. Windows systems use a different but conceptually similar mechanism for tracking resources. To simplify things for users, Node.js abstracts away the specific differences between operating systems and assigns all open files a numeric file descriptor.
The method is used to allocate a new file descriptor.
Once allocated, the file descriptor may be used to read data from, write data to, or request information about the file.
use stat always close the file descriptor!
Most operating systems limit the number of file descriptors that may be open at any given time so it is critical to close the descriptor when operations are completed. Failure to do so will result in a memory leak that will eventually cause an application to crash.
Threadpool Usage
Note that all file system APIs except and those that are explicitly synchronous use libuv's threadpool, which can have surprising and negative performance implications for some applications, see the documentation for more information.
A successful call to method will return a new object.
All objects are that will emit a event whenever a specific watched file is modified.
The type of change event that has occurred
The filename that changed (if relevant/available)
Emitted when something changes in a watched directory or file.
See more details in
The argument may not be provided depending on operating system support.
If is provided, it will be provided as a if is called with its option set to, otherwise will be a UTF-8 string.
Example when handled through listener
Emitted when the watcher stops watching for changes.
Emitted when an error occurs while watching the file.
Stop watching for changes on the given
Once stopped, the object is no longer usable.
All objects are
Emitted when the underlying file descriptor has been closed.
Integer file descriptor used by the
Emitted when the file descriptor has been opened.
Emitted when the is ready to be used.
Fires immediately after
The number of bytes that have been read so far.
The path to the file the stream is reading from as specified in the first argument to
If is passed as a string, then will be a string.
If is passed as a, then will be a
A object provides information about a file.
Objects returned from and their synchronous counterparts are of this type.
Returns
Returns if the object describes a block device.
a character device.
a file system directory.
a first-in-first-out (FIFO) pipe.
a regular file.
a socket.
a symbolic link.
This method is only valid when using
The numeric identifier of the device containing the file.
The file system specific "Inode" number for the file.
A bit-field describing the file type and mode.
The number of hard-links that exist for the file.
The numeric user identifier of the user that owns the file (POSIX).
The numeric group identifier of the group that owns the file (POSIX).
A numeric device identifier if the file is considered "special".
The size of the file in bytes.
The file system block size for i/o operations.
The number of blocks allocated for this file.
The timestamp indicating the last time this file was accessed expressed in milliseconds since the POSIX Epoch.
The timestamp indicating the last time this file was accessed.
Stat Time Values
The properties are numbers that hold the corresponding times in milliseconds.
Their precision is platform specific.
and are object alternate representations of the various times.
The and number values are not connected.
Assigning a new number value, or mutating the value, will not be reflected in the corresponding alternate representation.
The times in the stat object have the following semantics:
"Access Time" - Time when file data last accessed.
Changed by the and system calls.
Set once when the file is created. On filesystems where birthtime is not available, this field may instead hold either the
Note that this value may be greater than or in this case.
On Darwin and other FreeBSD variants, also set if the is explicitly set to an earlier value than the current using the system call.
Prior to Node.js v0.12, the held the on Windows systems.
Note that as of v0.12, is not "creation time", and on Unix systems, it never was.