Next Previous Contents

11. Low-level POSIX I/O functions

11.1 close

Synopsis

Close an open file descriptor

Usage

Int_Type close (FD_Type fd)

Description

The close function is used to open file descriptor of type FD_Type. Upon success 0 is returned, otherwise the function returns -1 and sets errno accordingly.

See Also

open, fclose, read, write

11.2 dup_fd

Synopsis

Duplicate a file descriptor

Usage

FD_Type dup_fd (FD_Type fd)

Description

The dup_fd function duplicates and file descriptor and returns its duplicate. If the function fails, NULL will be returned and errno set accordingly.

Notes

This function is essentually a wrapper around the POSIX dup function.

See Also

open, close

11.3 fileno

Synopsis

Convert a stdio File_Type object to a FD_Type descriptor

Usage

FD_Type fileno (File_Type fp)

Description

The fileno function returns the FD_Type descriptor associated with the File_Type file pointer. Upon failure, NULL is returned.

See Also

fopen, open, fclose, close, dup_fd

11.4 isatty

Synopsis

Determine if an open file descriptor refers to a terminal

Usage

Int_Type isatty (FD_Type or File_Type fd)

Description

This function returns 1 if the file descriptor fd refers to a terminal; otherwise it returns 0. The object fd may either be a File_Type stdio descriptor or an FD_Type object.

See Also

fopen, fclose, fileno

11.5 lseek

Synopsis

Reposition a file descriptor's file pointer

Usage

Long_Type lseek (FD_Type fd, Long_Type ofs, int mode) The lseek function repositions the file pointer associated with the open file descriptor fp to offset ofs according to the mode parameter. Specifically, mode must be one of the values:

     SEEK_SET   Set the offset to ofs
     SEEK_CUR   Add ofs to the current offset
     SEEK_END   Add ofs to the current file size
Upon error, lseek returns -1 and sets errno. If successful, it returns the new filepointer offset.
Notes

Not all file descriptors are capable of supporting the seek operation, e.g., a descriptor associated with a pipe.

By using SEEK_END with a positive value of the ofs parameter, it is possible to position the file pointer beyond the current size of the file.

See Also

fseek, ftell, open, close

11.6 open

Synopsis

Open a file

Usage

FD_Type open (String_Type filename, Int_Type flags [,Int_Type mode])

Description

The open function attempts to open a file specified by the filename parameter according to the flags parameter, which must be one of the following values:

     O_RDONLY   (read-only)
     O_WRONLY   (write-only)
     O_RDWR     (read/write)
In addition, flags may also be bitwise-or'd with any of the following:
     O_BINARY   (open the file in binary mode)
     O_TEXT     (open the file in text mode)
     O_CREAT    (create file if it does not exists)
     O_EXCL     (fail if the file already exists)
     O_NOCTTY   (do not make the device the controlling terminal)
     O_TRUNC    (truncate the file if it exists)
     O_APPEND   (open the file in append mode)
     O_NONBLOCK (open the file in non-blocking mode)
If O_CREAT is used for the flags parameterm then the mode parameter must be present. mode specifies the permissions to use if a new file is created. The actual file permissions will be affected by the process's umask via mode&~umask. The mode parameter's value is constructed via bitwise-or of the following values:
     S_IRWXU    (Owner has read/write/execute permission)
     S_IRUSR    (Owner has read permission)
     S_IWUSR    (Owner has write permission)
     S_IXUSR    (Owner has execute permission)
     S_IRWXG    (Group has read/write/execute permission)
     S_IRGRP    (Group has read permission)
     S_IWGRP    (Group has write permission)
     S_IXGRP    (Group has execute permission)
     S_IRWXO    (Others have read/write/execute permission)
     S_IROTH    (Others have read permission)
     S_IWOTH    (Others have write permission)
     S_IXOTH    (Others have execute permission)
Upon success open returns a file descriptor object (FD_Type), otherwise NULL is returned and errno is set.
Notes

If you are not familiar with the open system call, then it is recommended that you use fopen instead.

See Also

fopen, close, read, write, stat_file

11.7 read

Synopsis

Read from an open file descriptor

Usage

UInt_Type read (FD_Type fd, Ref_Type buf, UInt_Type num)

Description

The read function attempts to read at most num bytes into the variable indicated by buf from the open file descriptor fd. It returns the number of bytes read, or -1 and sets errno upon failure. The number of bytes read may be less than num, and will be zero if an attempt is made to read past the end of the file.

Notes

read is a low-level function and may return -1 for a variety of reasons. For example, if non-blocking I/O has been specified for the open file descriptor and no data is available for reading then the function will return -1 and set errno to EAGAIN.

See Also

fread, open, close, write

11.8 write

Synopsis

Write to an open file descriptor

Usage

UInt_Type write (FD_Type fd, BString_Type buf

Description

The write function attempts to write the bytes specified by the buf parameter to the open file descriptor fd. It returns the number of bytes successfully written, or -1 and sets errno upon failure. The number of bytes written may be less than length(buf).

See Also

read, fwrite, open, close


Next Previous Contents