Next Previous Contents

15. Low-level POSIX I/O functions

15.1 close

Synopsis

Close an open file descriptor

Usage

Int_Type close (FD_Type fd)

Description

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

See Also

open, _close, fclose, read, write

15.2 _close

Synopsis

Close an open file descriptor

Usage

Int_Type _close (Int_Type fd)

Description

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

See Also

open, _fileno, close, fclose, read, write

15.3 dup_fd

Synopsis

Duplicate a file descriptor

Usage

FD_Type dup_fd (FD_Type fd)

Description

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

Notes

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

See Also

open, close

15.4 dup2_fd

Synopsis

Duplicate a file descriptor

Usage

Int_Type dup2_fd (FD_Type fd, int newfd)

Description

The dup2_fd function makes newfd a copy of the specified file descriptor fd. Upon success returns newfd, otherwise it returns -1 and sets errno accordingly.

See Also

dup, open, close, _close, _fileno, read

15.5 _fileno

Synopsis

Get the underlying integer file descriptor

Usage

Int_Type _fileno (File_Type|FD_Type fp)

Description

The _fileno function returns the underlying integer descriptor for a specified stdio File_Type or FD_Type object. Upon failure it returns -1 and sets errno accordingly.

See Also

fileno, fopen, open, fclose, close, dup_fd

15.6 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 stdio File_Type file pointer. Upon failure, NULL is returned.

Notes

Closing the resulting file descriptor will have no effect.

See Also

fopen, open, fclose, close, dup_fd, _fileno

15.7 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 a lower-level FD_Type object.

See Also

fopen, fclose, fileno

15.8 lseek

Synopsis

Reposition a file descriptor's file pointer

Usage

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

     SEEK_SET   Set the offset to ofs from the beginning of the file
     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

15.9 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 the file if it does not exist)
     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)
Some of these flags make sense only when combined with other flags. For example, if O_EXCL is used, then O_CREAT must also be specified, otherwise unpredictable behavior may result.

If O_CREAT is used for the flags parameter 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 and use the higher level stdio interface.

See Also

fopen, close, read, write, stat_file

15.10 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 upon failure and sets errno. 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

15.11 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