<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
<TITLE> S-Lang Run-Time Library Reference: Version 1.4.0: Low-level POSIX I/O functions</TITLE>
<LINK HREF="slangfun-12.html" REL=next>
<LINK HREF="slangfun-10.html" REL=previous>
<LINK HREF="slangfun.html#toc11" REL=contents>
</HEAD>
<BODY>
<A HREF="slangfun-12.html">Next</A>
<A HREF="slangfun-10.html">Previous</A>
<A HREF="slangfun.html#toc11">Contents</A>
<HR>
<H2><A NAME="s11">11. Low-level POSIX I/O functions</A></H2>
<P>
<H2><A NAME="close"></A> <A NAME="ss11.1">11.1 <B>close</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Close an open file descriptor
<DT><B> Usage </B><DD><P><CODE>Int_Type close (FD_Type fd)</CODE>
<DT><B> Description </B><DD><P>The <CODE>close</CODE> function is used to open file descriptor of type
<CODE>FD_Type</CODE>. Upon success <CODE>0</CODE> is returned, otherwise the function
returns <CODE>-1</CODE> and sets <CODE>errno</CODE> accordingly.
<DT><B> See Also </B><DD><P><CODE>open, fclose, read, write</CODE>
</DL>
<P>
<P>
<H2><A NAME="dup_fd"></A> <A NAME="ss11.2">11.2 <B>dup_fd</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Duplicate a file descriptor
<DT><B> Usage </B><DD><P><CODE>FD_Type dup_fd (FD_Type fd)</CODE>
<DT><B> Description </B><DD><P>The <CODE>dup_fd</CODE> function duplicates and file descriptor and returns
its duplicate. If the function fails, <CODE>NULL</CODE> will be returned and
<CODE>errno</CODE> set accordingly.
<DT><B> Notes </B><DD><P>This function is essentually a wrapper around the POSIX <CODE>dup</CODE>
function.
<DT><B> See Also </B><DD><P><CODE>open, close</CODE>
</DL>
<P>
<P>
<H2><A NAME="fileno"></A> <A NAME="ss11.3">11.3 <B>fileno</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Convert a stdio File_Type object to a FD_Type descriptor
<DT><B> Usage </B><DD><P><CODE>FD_Type fileno (File_Type fp)</CODE>
<DT><B> Description </B><DD><P>The <CODE>fileno</CODE> function returns the <CODE>FD_Type</CODE> descriptor
associated with the <CODE>File_Type</CODE> file pointer. Upon failure,
<CODE>NULL</CODE> is returned.
<DT><B> See Also </B><DD><P><CODE>fopen, open, fclose, close, dup_fd</CODE>
</DL>
<P>
<P>
<H2><A NAME="isatty"></A> <A NAME="ss11.4">11.4 <B>isatty</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Determine if an open file descriptor refers to a terminal
<DT><B> Usage </B><DD><P><CODE>Int_Type isatty (FD_Type or File_Type fd)</CODE>
<DT><B> Description </B><DD><P>This function returns <CODE>1</CODE> if the file descriptor <CODE>fd</CODE> refers to a
terminal; otherwise it returns <CODE>0</CODE>. The object <CODE>fd</CODE> may either
be a <CODE>File_Type</CODE> stdio descriptor or an <CODE>FD_Type</CODE> object.
<DT><B> See Also </B><DD><P><CODE>fopen, fclose, fileno</CODE>
</DL>
<P>
<P>
<H2><A NAME="lseek"></A> <A NAME="ss11.5">11.5 <B>lseek</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Reposition a file descriptor's file pointer
<DT><B> Usage </B><DD><P><CODE>Long_Type lseek (FD_Type fd, Long_Type ofs, int mode)</CODE>
The <CODE>lseek</CODE> function repositions the file pointer associated
with the open file descriptor <CODE>fp</CODE> to offset <CODE>ofs</CODE>
according to the mode parameter. Specifically, <CODE>mode</CODE> must be
one of the values:
<BLOCKQUOTE><CODE>
<PRE>
SEEK_SET Set the offset to ofs
SEEK_CUR Add ofs to the current offset
SEEK_END Add ofs to the current file size
</PRE>
</CODE></BLOCKQUOTE>
Upon error, <CODE>lseek</CODE> returns <CODE>-1</CODE> and sets <CODE>errno</CODE>. If
successful, it returns the new filepointer offset.
<DT><B> Notes </B><DD><P>Not all file descriptors are capable of supporting the seek
operation, e.g., a descriptor associated with a pipe.
<P>By using <CODE>SEEK_END</CODE> with a positive value of the <CODE>ofs</CODE>
parameter, it is possible to position the file pointer beyond the
current size of the file.
<DT><B> See Also </B><DD><P><CODE>fseek, ftell, open, close</CODE>
</DL>
<P>
<P>
<H2><A NAME="open"></A> <A NAME="ss11.6">11.6 <B>open</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Open a file
<DT><B> Usage </B><DD><P><CODE>FD_Type open (String_Type filename, Int_Type flags [,Int_Type mode])</CODE>
<DT><B> Description </B><DD><P>The <CODE>open</CODE> function attempts to open a file specified by the
<CODE>filename</CODE> parameter according to the <CODE>flags</CODE> parameter,
which must be one of the following values:
<BLOCKQUOTE><CODE>
<PRE>
O_RDONLY (read-only)
O_WRONLY (write-only)
O_RDWR (read/write)
</PRE>
</CODE></BLOCKQUOTE>
In addition, <CODE>flags</CODE> may also be bitwise-or'd with any of the
following:
<BLOCKQUOTE><CODE>
<PRE>
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)
</PRE>
</CODE></BLOCKQUOTE>
If <CODE>O_CREAT</CODE> is used for the <CODE>flags</CODE> parameterm then the
<CODE>mode</CODE> parameter must be present. <CODE>mode</CODE> specifies the
permissions to use if a new file is created. The actual file
permissions will be affected by the process's <CODE>umask</CODE> via
<CODE>mode&~umask</CODE>. The <CODE>mode</CODE> parameter's value is
constructed via bitwise-or of the following values:
<BLOCKQUOTE><CODE>
<PRE>
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)
</PRE>
</CODE></BLOCKQUOTE>
Upon success <CODE>open</CODE> returns a file descriptor object
(<CODE>FD_Type</CODE>), otherwise <CODE>NULL</CODE> is returned and <CODE>errno</CODE>
is set.
<DT><B> Notes </B><DD><P>If you are not familiar with the <CODE>open</CODE> system call, then it
is recommended that you use <CODE>fopen</CODE> instead.
<DT><B> See Also </B><DD><P><CODE>fopen, close, read, write, stat_file</CODE>
</DL>
<P>
<P>
<H2><A NAME="read"></A> <A NAME="ss11.7">11.7 <B>read</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Read from an open file descriptor
<DT><B> Usage </B><DD><P><CODE>UInt_Type read (FD_Type fd, Ref_Type buf, UInt_Type num)</CODE>
<DT><B> Description </B><DD><P>The <CODE>read</CODE> function attempts to read at most <CODE>num</CODE> bytes
into the variable indicated by <CODE>buf</CODE> from the open file
descriptor <CODE>fd</CODE>. It returns the number of bytes read, or <CODE>-1</CODE>
and sets <CODE>errno</CODE> upon failure. The number of bytes read may be
less than <CODE>num</CODE>, and will be zero if an attempt is made to read
past the end of the file.
<DT><B> Notes </B><DD><P><CODE>read</CODE> is a low-level function and may return <CODE>-1</CODE> 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 <CODE>-1</CODE> and set <CODE>errno</CODE> to <CODE>EAGAIN</CODE>.
<DT><B> See Also </B><DD><P><CODE>fread, open, close, write</CODE>
</DL>
<P>
<P>
<H2><A NAME="write"></A> <A NAME="ss11.8">11.8 <B>write</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Write to an open file descriptor
<DT><B> Usage </B><DD><P><CODE>UInt_Type write (FD_Type fd, BString_Type buf</CODE>
<DT><B> Description </B><DD><P>The <CODE>write</CODE> function attempts to write the bytes specified by
the <CODE>buf</CODE> parameter to the open file descriptor <CODE>fd</CODE>. It
returns the number of bytes successfully written, or <CODE>-1</CODE> and sets
<CODE>errno</CODE> upon failure. The number of bytes written may be less
than <CODE>length(buf)</CODE>.
<DT><B> See Also </B><DD><P><CODE>read, fwrite, open, close</CODE>
</DL>
<P>
<P>
<P>
<HR>
<A HREF="slangfun-12.html">Next</A>
<A HREF="slangfun-10.html">Previous</A>
<A HREF="slangfun.html#toc11">Contents</A>
</BODY>
</HTML>
