aboutsummaryrefslogtreecommitdiff
path: root/manual/llio.texi
diff options
context:
space:
mode:
Diffstat (limited to 'manual/llio.texi')
-rw-r--r--manual/llio.texi216
1 files changed, 214 insertions, 2 deletions
diff --git a/manual/llio.texi b/manual/llio.texi
index 4c10b72578..23c5f767f1 100644
--- a/manual/llio.texi
+++ b/manual/llio.texi
@@ -32,6 +32,7 @@ directly.)
@menu
* Opening and Closing Files:: How to open and close file
descriptors.
+* Truncating Files:: Change the size of a file.
* I/O Primitives:: Reading and writing data.
* File Position Primitive:: Setting a descriptor's file
position.
@@ -41,6 +42,7 @@ directly.)
descriptors and streams.
* Waiting for I/O:: How to check for input or output
on multiple file descriptors.
+* Synchronizing I/O:: Making sure all I/O actions completed.
* Control Operations:: Various other operations on file
descriptors.
* Duplicating Descriptors:: Fcntl commands for duplicating
@@ -136,6 +138,14 @@ or @code{O_CREAT} is set and the file does not already exist.
@c !!! umask
+This function is a cancelation point in multi-threaded programs. This
+is a problem if the thread allocates some resources (like memory, file
+descriptors, semaphores or whatever) at the time @code{open} is
+called. If the thread gets canceled these resources stay allocated
+until the program ends. To avoid this calls to @code{open} should be
+protected using cancelation handlers.
+@c ref pthread_cleanup_push / pthread_cleanup_pop
+
The @code{open} function is the underlying primitive for the @code{fopen}
and @code{freopen} functions, that create streams.
@end deftypefun
@@ -175,6 +185,14 @@ When all file descriptors associated with a pipe or FIFO have been closed,
any unread data is discarded.
@end itemize
+This function is a cancelation point in multi-threaded programs. This
+is a problem if the thread allocates some resources (like memory, file
+descriptors, semaphores or whatever) at the time @code{close} is
+called. If the thread gets canceled these resources stay allocated
+until the program ends. To avoid this calls to @code{close} should be
+protected using cancelation handlers.
+@c ref pthread_cleanup_push / pthread_cleanup_pop
+
The normal return value from @code{close} is @code{0}; a value of @code{-1}
is returned in case of failure. The following @code{errno} error
conditions are defined for this function:
@@ -206,6 +224,73 @@ of trying to close its underlying file descriptor with @code{close}.
This flushes any buffered output and updates the stream object to
indicate that it is closed.
+
+@node Truncating Files
+@section Change the size of a file
+
+In some situations it is useful to explicitly determine the size of a
+file. Since the 4.2BSD days there is a function to truncate a file to
+at most a given number of bytes and POSIX defines one additional
+function. The prototypes for these functions are in @file{unistd.h}.
+
+@comment unistd.h
+@comment X/Open
+@deftypefun int truncate (const char *@var{name}, size_t @var{length})
+The @code{truncation} function truncates the file named by @var{name} to
+at most @var{length} bytes. I.e., if the file was larger before the
+extra bytes are stripped of. If the file was small or equal to
+@var{length} in size before nothing is done. The file must be writable
+by the user to perform this operation.
+
+The return value is zero is everything wnet ok. Otherwise the return
+value is @math{-1} and the global variable @var{errno} is set to:
+@table @code
+@item EACCES
+The file is not accessible to the user.
+@item EINVAL
+The @var{length} value is illegal.
+@item EISDIR
+The object named by @var{name} is a directory.
+@item ENOENT
+The file named by @var{name} does not exist.
+@item ENOTDIR
+One part of the @var{name} is not a directory.
+@end table
+
+This function was introduced in 4.2BSD but also was available in later
+@w{System V} systems. It is not added to POSIX since the authors felt
+it is only of marginally additional utility. See below.
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX
+@deftypefun int ftruncate (int @var{fd}, size_t @var{length})
+The @code{ftruncate} function is similar to the @code{truncate}
+function. The main difference is that it takes a descriptor for an
+opened file instead of a file name to identify the object. The file
+must be opened for writing to successfully carry out the operation.
+
+The POSIX standard leaves it implementation defined what happens if the
+specified new @var{length} of the file is bigger than the original size.
+The @code{ftruncate} function might simply leave the file alone and do
+nothing or it can increase the size to the desired size. In this later
+case the extended area should be zero-filled. So using @code{ftruncate}
+is no reliable way to increase the file size but if it is possible it is
+probably the fastest way. The function also operates on POSIX shared
+memory segments if these are implemented by the system.
+
+On success the function returns zero. Otherwise it returns @math{-1}
+and set @var{errno} to one of these values:
+@table @code
+@item EBADF
+@var{fd} is no valid file descriptor or is not opened for writing.
+@item EINVAL
+The object referred to by @var{fd} does not permit this operation.
+@item EROFS
+The file is on a read-only file system.
+@end table
+@end deftypefun
+
@node I/O Primitives
@section Input and Output Primitives
@@ -297,6 +382,14 @@ orphaned. @xref{Job Control}, for more information about job control,
and @ref{Signal Handling}, for information about signals.
@end table
+This function is a cancelation point in multi-threaded programs. This
+is a problem if the thread allocates some resources (like memory, file
+descriptors, semaphores or whatever) at the time @code{read} is
+called. If the thread gets canceled these resources stay allocated
+until the program ends. To avoid this calls to @code{read} should be
+protected using cancelation handlers.
+@c ref pthread_cleanup_push / pthread_cleanup_pop
+
The @code{read} function is the underlying primitive for all of the
functions that read from streams, such as @code{fgetc}.
@end deftypefun
@@ -419,6 +512,14 @@ macro @code{TEMP_FAILURE_RETRY}, as follows:
nbytes = TEMP_FAILURE_RETRY (write (desc, buffer, count));
@end smallexample
+This function is a cancelation point in multi-threaded programs. This
+is a problem if the thread allocates some resources (like memory, file
+descriptors, semaphores or whatever) at the time @code{write} is
+called. If the thread gets canceled these resources stay allocated
+until the program ends. To avoid this calls to @code{write} should be
+protected using cancelation handlers.
+@c ref pthread_cleanup_push / pthread_cleanup_pop
+
The @code{write} function is the underlying primitive for all of the
functions that write to streams, such as @code{fputc}.
@end deftypefun
@@ -537,9 +638,18 @@ only for pipes and FIFOs, but in the GNU system, you always get
@code{ESPIPE} if the object is not seekable.)
@end table
+This function is a cancelation point in multi-threaded programs. This
+is a problem if the thread allocates some resources (like memory, file
+descriptors, semaphores or whatever) at the time @code{lseek} is
+called. If the thread gets canceled these resources stay allocated
+until the program ends. To avoid this calls to @code{lseek} should be
+protected using cancelation handlers.
+@c ref pthread_cleanup_push / pthread_cleanup_pop
+
The @code{lseek} function is the underlying primitive for the
-@code{fseek}, @code{ftell} and @code{rewind} functions, which operate on
-streams instead of file descriptors.
+@code{fseek}, @code{fseeko}, @code{ftell}, @code{ftello} and
+@code{rewind} functions, which operate on streams instead of file
+descriptors.
@end deftypefun
You can have multiple descriptors for the same file if you open the file
@@ -1007,6 +1117,100 @@ There is another example showing the use of @code{select} to multiplex
input from multiple sockets in @ref{Server Example}.
+@node Synchronizing I/O
+@section Synchronizing I/O operations
+
+@cindex synchronizing
+In most modern operation systems the normal I/O operations are not
+executed synchronously. I.e., even if a @code{write} system call
+returns this does not mean the data is actually written to the media,
+e.g., the disk.
+
+In situations where synchronization points are necessary the user can
+use special functions which ensure that all operations finished before
+they return.
+
+@comment unistd.h
+@comment X/Open
+@deftypefun int sync (void)
+A call to this function will not return as long as there is data which
+that is not written to the device. All dirty buffers in the kernel will
+be written and so an overall consistent system can be achieved (if no
+other process in parallel writes data).
+
+A prototype for @code{sync} can be found in @file{unistd.h}.
+
+The return value is zero to indicate no error.
+@end deftypefun
+
+More often it is wanted that not all data in the system is committed.
+Programs want to ensure that data written to a given file are all
+committed and in this situation @code{sync} is overkill.
+
+@comment unistd.h
+@comment POSIX
+@deftypefun int fsync (int @var{fildes})
+The @code{fsync} can be used to make sure all data associated with the
+open file @var{fildes} is written to the device associated with the
+descriptor. The function call does not return unless all actions have
+finished.
+
+A prototype for @code{fsync} can be found in @file{unistd.h}.
+
+This function is a cancelation point in multi-threaded programs. This
+is a problem if the thread allocates some resources (like memory, file
+descriptors, semaphores or whatever) at the time @code{fsync} is
+called. If the thread gets canceled these resources stay allocated
+until the program ends. To avoid this calls to @code{fsync} should be
+protected using cancelation handlers.
+@c ref pthread_cleanup_push / pthread_cleanup_pop
+
+The return value of the function is zero if no error occured. Otherwise
+it is @math{-1} and the global variable @var{errno} is set to the
+following values:
+@table @code
+@item EBADF
+The descriptor @var{fildes} is not valid.
+
+@item EINVAL
+No synchronization is possible since the system does not implement this.
+@end table
+@end deftypefun
+
+Sometimes it is not even necessary to write all data associated with a
+file descriptor. E.g., in database files which do not change in size it
+is enough to write all the file content data to the device.
+Metainformation like the modification time etc. are not that important
+and leaving such information uncommitted does not prevent a successful
+recovering of the file in case of a problem.
+
+@comment unistd.h
+@comment POSIX
+@deftypefun int fdatasync (int @var{fildes})
+When a call to the @code{fdatasync} function returns it is maed sure
+that all of the file data is written to the device. For all pending I/O
+operations the parts guaranteeing data integrety finished.
+
+Not all systems implement the @code{fdatasync} operation. On systems
+missing this functionality @code{fdatasync} is emulated by a call to
+@code{fsync} since the performed actions are a superset of those
+required by @code{fdatasyn}.
+
+The prototype for @code{fdatasync} is in @file{unistd.h}.
+
+The return value of the function is zero if no error occured. Otherwise
+it is @math{-1} and the global variable @var{errno} is set to the
+following values:
+@table @code
+@item EBADF
+The descriptor @var{fildes} is not valid.
+
+@item EINVAL
+No synchronization is possible since the system does not implement this.
+@end table
+@end deftypefun
+
+
@node Control Operations
@section Control Operations on Files
@@ -1069,6 +1273,14 @@ Get process or process group ID to receive @code{SIGIO} signals.
Set process or process group ID to receive @code{SIGIO} signals.
@xref{Interrupt Input}.
@end table
+
+This function is a cancelation point in multi-threaded programs. This
+is a problem if the thread allocates some resources (like memory, file
+descriptors, semaphores or whatever) at the time @code{fcntl} is
+called. If the thread gets canceled these resources stay allocated
+until the program ends. To avoid this calls to @code{fcntl} should be
+protected using cancelation handlers.
+@c ref pthread_cleanup_push / pthread_cleanup_pop
@end deftypefun