diff options
Diffstat (limited to 'manual/llio.texi')
| -rw-r--r-- | manual/llio.texi | 216 |
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 |