posix.sgml

ecos实时嵌入式操作系统

<!-- {{{ Banner                         -->

<!-- =============================================================== -->
<!--                                                                 -->
<!--     posix.sgml                                                  -->
<!--                                                                 -->
<!--     POSIX Compatibility                                         -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- ####COPYRIGHTBEGIN####                                          -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Red Hat, Inc.  -->
<!-- This material may be distributed only subject to the terms      -->
<!-- and conditions set forth in the Open Publication License, v1.0  -->
<!-- or later (the latest version is presently available at          -->
<!-- http://www.opencontent.org/openpub/)                            -->
<!-- Distribution of the work or derivative of the work in any       -->
<!-- standard (paper) book form is prohibited unless prior           -->
<!-- permission obtained from the copyright holder                   -->
<!-- =============================================================== -->
<!--                                                                 -->      
<!-- ####COPYRIGHTEND####                                            -->
<!-- =============================================================== -->
<!-- #####DESCRIPTIONBEGIN####                                       -->
<!--                                                                 -->
<!-- ####DESCRIPTIONEND####                                          -->
<!-- =============================================================== -->

<!-- }}} -->

<part id="posix-compatibility">
<title>eCos POSIX compatibility layer</title>

<chapter id="posix-standard-support">
<title>POSIX Standard Support</title>

<!-- {{{ Intro  -->

    <para>
      eCos contains support for the POSIX Specification (ISO&sol;IEC
      9945-1)&lsqb;POSIX&rsqb;.
    </para>
    <para>
      POSIX support is divided between the POSIX and the FILEIO
      packages. The POSIX package provides support for threads,
      signals, synchronization, timers and message queues. The FILEIO
      package provides support for file and device I&sol;O. The two
      packages may be used together or separately, depending on
      configuration.
    </para>
    <para>
      This document takes a functional approach to the POSIX
      library. Support for a function implies that the data types and
      definitions necessary to support that function, and the objects
      it manipulates, are also defined. Any exceptions to this are
      noted, and unless otherwise noted, implemented functions behave
      as specified in the POSIX standard.
    </para>
    <para>
      This document only covers the differences between the eCos
      implementation and the standard; it does not provide complete
      documentation. For full information, see the POSIX standard
      &lsqb;POSIX&rsqb;. Online, the Open Group Single Unix
      Specification &lsqb;SUS2&rsqb; provides complete documentation
      of a superset of POSIX. If you have access to a Unix system with
      POSIX compatibility, then the manual pages for this will be of
      use.  There are also a number of books available.
      &lsqb;Lewine&rsqb; covers the process, signal, file and I&sol;O
      functions, while &lsqb;Lewis1&rsqb;, &lsqb;Lewis2&rsqb;,
      &lsqb;Nichols&rsqb; and &lsqb;Norton&rsqb; cover Pthreads and
      related topics (see Bibliography, xref). However, many of these
      books are oriented toward using POSIX in non-embedded systems,
      so care should be taken in applying them to programming under
      eCos.
    </para>
    <para>
      The remainder of this chapter broadly follows the structure
      of the POSIX Specification. References to the appropriate
      section of the Standard are included.
    </para>
    <para>
      Omitted functions marked with &ldquo;&sol;&sol; TBA&rdquo;
      are potential candidates for later implementation.
    </para>

<!-- }}} -->
<!-- {{{ Process Primitives -->

<sect1 id="posix-process-primitives">
<title>Process Primitives &lsqb;POSIX Section 3&rsqb;</title>

<!-- =================================================================== -->

<sect2>
<title>Functions Implemented</title>

<screen>
int kill(pid&lowbar;t pid, int sig); 
int pthread&lowbar;kill(pthread&lowbar;t thread, int sig); 
int sigaction(int sig, const struct sigaction &ast;act,
              struct sigaction &ast;oact); 
int sigqueue(pid&lowbar;t pid, int sig, const union sigval value); 
int sigprocmask(int how, const sigset&lowbar;t &ast;set,
                sigset&lowbar;t &ast;oset); 
int pthread&lowbar;sigmask(int how, const sigset&lowbar;t &ast;set,
                    sigset&lowbar;t &ast;oset); 
int sigpending(sigset&lowbar;t &ast;set);
int sigsuspend(const sigset&lowbar;t &ast;set); 
int sigwait(const sigset&lowbar;t &ast;set, int &ast;sig); 
int sigwaitinfo(const sigset&lowbar;t &ast;set, siginfo&lowbar;t &ast;info); 
int sigtimedwait(const sigset&lowbar;t &ast;set, siginfo&lowbar;t &ast;info,
                 const struct timespec &ast;timeout); 
int sigemptyset(sigset&lowbar;t &ast;set); 
int sigfillset(sigset&lowbar;t &ast;set); 
int sigaddset(sigset&lowbar;t &ast;set, int signo); 
int sigdelset(sigset&lowbar;t &ast;set, int signo); 
int sigismember(const sigset&lowbar;t &ast;set, int signo);
unsigned int alarm( unsigned int seconds );
int pause( void ); 
unsigned int sleep( unsigned int seconds );
</screen>
</sect2>

<!-- =================================================================== -->

<sect2>
<title>Functions Omitted</title>

<screen>
pid&lowbar;t fork(void); 
int execl( const char &ast;path, const char &ast;arg, ... ); 
int execv( const char &ast;path, char &ast;const argv&lsqb;&rsqb; ); 
int execle( const char &ast;path, const char &ast;arg, ... ); 
int execve( const char &ast;path, char &ast;const argv&lsqb;&rsqb;,
            char &ast;const envp&lsqb;&rsqb; ); 
int execlp( const char &ast;path, const char &ast;arg, ... ); 
int execvp( const char &ast;path, char &ast;const argv&lsqb;&rsqb; ); 
int pthread&lowbar;atfork( void(&ast;prepare)(void),
                    void (&ast;parent)(void),
                    void (&ast;child)() );
pid&lowbar;t wait( int &ast;stat&lowbar;loc );		    
pid&lowbar;t waitpid( pid&lowbar;t pid, int &ast;stat&lowbar;loc,
               int options ); 
void &lowbar;exit( int status );
</screen>
</sect2>

<!-- =================================================================== -->

<sect2>
<title>Notes</title>
<itemizedlist>
  <listitem>
    <para>
    Signal handling may be enabled or disabled with the
    CYGPKG&lowbar;POSIX&lowbar;SIGNALS option. Since signals are used
    by other POSIX components, such as timers, disabling signals will
    disable those components too.
    </para>
  </listitem>
  
  <listitem>
    <para>
    <emphasis>kill()</emphasis> and
    <emphasis>sigqueue()</emphasis> may only take a 
    <emphasis role="strong">pid</emphasis> argument of zero,
    which maps to the current process.
    </para>
  </listitem>
  
  <listitem>
    <para>
    The <emphasis>SIGEV&lowbar;THREAD</emphasis> notification type is
	    not currently implemented.
    </para>
  </listitem>
  
  <listitem>
    <para>
    Job Control and Memory Protection signals are
	    not supported.
    </para>
  </listitem>

  <listitem>
    <para>
    An extra implementation defined
    <emphasis>si&lowbar;code</emphasis> value,
    <emphasis>SI&lowbar;EXCEPT</emphasis>, is defined to
    distinguish hardware generated exceptions from
    others.
    </para>
  </listitem>

  <listitem>
    <para>
    Extra signals are defined:
    &lowbar;SIGTRAP&lowbar;,&lowbar;SIGIOT&lowbar;,
    &lowbar;SIGEMT&lowbar;, and &lowbar;SIGSYS&lowbar;. These are
    largely to maintain compatibility with the signal numbers used by
    GDB.
    </para>
  </listitem>

  <listitem>
    <para>
    Signal delivery may currently occur at unexpected places in some
    API functions. Using <emphasis>longjmp()</emphasis> to transfer
    control out of a signal handler may result in the interrupted
    function not being able to complete properly. This may result in
    later function calls failing or deadlocking.
    </para>
  </listitem>
</itemizedlist>
</sect2>


</sect1>

<!-- }}} -->
<!-- {{{ Process Environment -->

<sect1 id="posix-process-environment">
<title>Process Environment &lsqb;POSIX Section 4&rsqb;</title>

<!-- =================================================================== -->

<sect2>
<title>Functions Implemented</title>

<screen>
int uname( struct utsname &ast;name ); 
time&lowbar;t time( time&lowbar;t &ast;tloc ); 
char &ast;getenv( const char &ast;name ); 
int isatty( int fd );
long sysconf( int name );
</screen>
</sect2>

<!-- =================================================================== -->

<sect2>
<title>Functions Omitted</title>
<screen>
pid&lowbar;t getpid( void ); 
pid&lowbar;t getppid( void ); 
uid&lowbar;t getuid( void ); 
uid&lowbar;t geteuid( void ); 
gid&lowbar;t getgid( void ); 
gid&lowbar;t getegid( void ); 
int setuid( uid&lowbar;t uid ); 
int setgid( gid&lowbar;t gid ); 
int getgroups( int gidsetsize, gid&lowbar;t grouplist&lsqb;&rsqb; ); 
char &ast;getlogin( void ); 
int getlogin&lowbar;r( char &ast;name, size&lowbar;t namesize ); 
pid&lowbar;t getpgrp( void ); 
pid&lowbar;t setsid( void );
int setpgid( pid&lowbar;t pid, pid&lowbar;t pgid ); 
char &ast;ctermid( char &ast;s); 
char &ast;ttyname( int fd );                             &sol;&sol; TBA 
int ttyname&lowbar;r( int fd, char &ast;name, size&lowbar;t namesize); &sol;&sol; TBA 
clock&lowbar;t times( struct tms &ast;buffer );                 &sol;&sol; TBA
</screen>
</sect2>

<!-- =================================================================== -->

<sect2>
<title>Notes</title>
	<itemizedlist>
	  <listitem>
	    <para>The fields of the <emphasis>utsname</emphasis>
	    structure are initialized as follows:
            <screen>
	    sysname	&ldquo;eCos&rdquo; 
	    nodename	&ldquo;&rdquo;	(gethostname() is currently not available)
	    
	    release		Major version number of the kernel 
	    version   		Minor version number of the kernel 
	    machine	&ldquo;&rdquo; 	(Requires some config tool changes)
            </screen>
	    </para>
	    <para>
	    The sizes of these strings are defined by
	    CYG&lowbar;POSIX&lowbar;UTSNAME&lowbar;LENGTH and
	    CYG&lowbar;POSIX&lowbar;UTSNAME&lowbar;NODENAME&lowbar;LENGTH. The
	    latter defaults to the value of the former, but may also
	    be set independently to accommodate a longer node name.
	    </para>
	  </listitem>
	  
	  <listitem>
	    <para>
	    The <emphasis>time()</emphasis> function is currently
	    implemented in the C library.
	    </para>
	  </listitem>
	  
	  <listitem>
	    <para>A set of environment strings may be defined at configuration
	    time with the CYGDAT&lowbar;LIBC&lowbar;DEFAULT&lowbar;ENVIRONMENT
	    option. The application may also define an environment by direct
	    assignment to the <emphasis role="strong">environ</emphasis>
	    variable.
	    </para>
	  </listitem>
	  
	  <listitem>
	    <para>
	    At present <emphasis>isatty()</emphasis> assumes that
	    any character device is a tty and that all other devices are not
	    ttys. Since the only kind of device that eCos currently supports
	    is serial character devices, this is an adequate
	    distinction.
	    </para>
	  </listitem>
	  
	  <listitem>
	    <para>
	    All system variables supported by sysconf will yield a
	    value. However, those that are irrelevant to eCos will
	    either return the default minimum defined in
	    <filename>&lt;limits.h&gt;</filename>,
	    or zero.
	    </para>
	  </listitem>
	</itemizedlist>

</sect2>
</sect1>

<!-- }}} -->
<!-- {{{ Files and Directories -->

<sect1 id="posix-files-and-directories">
<title>Files and Directories &lsqb;POSIX Section 5&rsqb;</title>

<!-- =================================================================== -->

<sect2>
<title>Functions Implemented</title>

<screen>
DIR &ast;opendir( const char &ast;dirname ); 
struct dirent &ast;readdir( DIR &ast;dirp ); 
int readdir&lowbar;r( DIR &ast;dirp, struct dirent &ast;entry,
               struct dirent &ast;&ast;result ); 
void rewinddir( DIR &ast;dirp ); 
int closedir( DIR &ast;dirp ); 
int chdir( const char &ast;path ); 
char &ast;getcwd( char &ast;buf, size&lowbar;t size );
int open( const char &ast; path , int oflag , ... ); 
int creat( const char &ast; path, mode&lowbar;t mode ); 
int link( const char &ast;existing, const char &ast;new ); 
int mkdir( const char &ast;path, mode&lowbar;t mode ); 
int unlink( const char &ast;path ); 
int rmdir( const char &ast;path ); 
int rename( const char &ast;old, const char &ast;new ); 
int stat( const char &ast;path, struct stat &ast;buf ); 
int fstat( int fd, struct stat &ast;buf ); 
int access( const char &ast;path, int amode ); 
long pathconf(const char &ast;path, int name); 
long fpathconf(int fd, int name);
</screen>
</sect2>

<!-- =================================================================== -->

<sect2>
<title>Functions Omitted</title>

<screen>
mode&lowbar;t umask( mode&lowbar;t cmask ); 
int mkfifo( const char &ast;path, mode&lowbar;t mode ); 
int chmod( const char &ast;path, mode&lowbar;t mode );			&sol;&sol; TBA 
int fchmod( int fd, mode&lowbar;t mode );				&sol;&sol; TBA 
int chown( const char &ast;path, uid&lowbar;t owner, gid&lowbar;t group ); 
int utime( const char &ast;path, const struct utimbuf &ast;times );	&sol;&sol; TBA 
int ftruncate( int fd, off&lowbar;t length );                          &sol;&sol; TBA
</screen>
</sect2>

<!-- =================================================================== -->

<sect2>
<title>Notes</title>

	<itemizedlist>
	  <listitem>
	    <para>
	    If a call to <function>open()</function> or <function>creat()</function> supplies
	    the third &lowbar;mode&lowbar; parameter, it will