Subversion Repositories openrisc_me

      eCos contains support for the POSIX Specification (ISO/IEC

      9945-1)[POSIX].

      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/O. The two

      packages may be used together or separately, depending on

      configuration.

      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.

      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

      [POSIX]. Online, the Open Group Single Unix

      Specification [SUS2] 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.

      [Lewine] covers the process, signal, file and I/O

      functions, while [Lewis1], [Lewis2],

      [Nichols] and [Norton] 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.

      The remainder of this chapter broadly follows the structure

      of the POSIX Specification. References to the appropriate

      section of the Standard are included.

      Omitted functions marked with “// TBA”

      are potential candidates for later implementation.

int kill(pid_t pid, int sig);

int pthread_kill(pthread_t thread, int sig);

int sigaction(int sig, const struct sigaction *act,

              struct sigaction *oact);

int sigqueue(pid_t pid, int sig, const union sigval value);

int sigprocmask(int how, const sigset_t *set,

                sigset_t *oset);

int pthread_sigmask(int how, const sigset_t *set,

                    sigset_t *oset);

int sigpending(sigset_t *set);

int sigsuspend(const sigset_t *set);

int sigwait(const sigset_t *set, int *sig);

int sigwaitinfo(const sigset_t *set, siginfo_t *info);

int sigtimedwait(const sigset_t *set, siginfo_t *info,

                 const struct timespec *timeout);

int sigemptyset(sigset_t *set);

int sigfillset(sigset_t *set);

int sigaddset(sigset_t *set, int signo);

int sigdelset(sigset_t *set, int signo);

int sigismember(const sigset_t *set, int signo);

unsigned int alarm( unsigned int seconds );

int pause( void );

unsigned int sleep( unsigned int seconds );

pid_t fork(void);

int execl( const char *path, const char *arg, ... );

int execv( const char *path, char *const argv[] );

int execle( const char *path, const char *arg, ... );

int execve( const char *path, char *const argv[],

            char *const envp[] );

int execlp( const char *path, const char *arg, ... );

int execvp( const char *path, char *const argv[] );

int pthread_atfork( void(*prepare)(void),

                    void (*parent)(void),

                    void (*child)() );

pid_t wait( int *stat_loc );

pid_t waitpid( pid_t pid, int *stat_loc,

               int options );

void _exit( int status );

    Signal handling may be enabled or disabled with the

    CYGPKG_POSIX_SIGNALS option. Since signals are used

    by other POSIX components, such as timers, disabling signals will

    disable those components too.

    kill() and

    sigqueue() may only take a

    pid argument of zero,

    which maps to the current process.

    The SIGEV_THREAD notification type is

            not currently implemented.

    Job Control and Memory Protection signals are

            not supported.

    An extra implementation defined

    si_code value,

    SI_EXCEPT, is defined to

    distinguish hardware generated exceptions from

    others.

    Extra signals are defined:

    _SIGTRAP_,_SIGIOT_,

    _SIGEMT_, and _SIGSYS_. These are

    largely to maintain compatibility with the signal numbers used by

    GDB.

    Signal delivery may currently occur at unexpected places in some

    API functions. Using longjmp() 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.

int uname( struct utsname *name );

time_t time( time_t *tloc );

char *getenv( const char *name );

int isatty( int fd );

long sysconf( int name );

pid_t getpid( void );

pid_t getppid( void );

uid_t getuid( void );

uid_t geteuid( void );

gid_t getgid( void );

gid_t getegid( void );

int setuid( uid_t uid );

int setgid( gid_t gid );

int getgroups( int gidsetsize, gid_t grouplist[] );

char *getlogin( void );

int getlogin_r( char *name, size_t namesize );

pid_t getpgrp( void );

pid_t setsid( void );

int setpgid( pid_t pid, pid_t pgid );

char *ctermid( char *s);

char *ttyname( int fd );                             // TBA

int ttyname_r( int fd, char *name, size_t namesize); // TBA

clock_t times( struct tms *buffer );                 // TBA

            The fields of the utsname

            structure are initialized as follows:

            sysname     “eCos”

            nodename    “”      (gethostname() is currently not available)

            release             Major version number of the kernel

            version             Minor version number of the kernel

            machine     “”      (Requires some config tool changes)

            The sizes of these strings are defined by

            CYG_POSIX_UTSNAME_LENGTH and

            CYG_POSIX_UTSNAME_NODENAME_LENGTH. The

            latter defaults to the value of the former, but may also

            be set independently to accommodate a longer node name.

            The time() function is currently

            implemented in the C library.

            A set of environment strings may be defined at configuration

            time with the CYGDAT_LIBC_DEFAULT_ENVIRONMENT

            option. The application may also define an environment by direct

            assignment to the environ

            variable.

            At present isatty() 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.

            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

            <limits.h>,

            or zero.

DIR *opendir( const char *dirname );

struct dirent *readdir( DIR *dirp );

int readdir_r( DIR *dirp, struct dirent *entry,

               struct dirent **result );

void rewinddir( DIR *dirp );

int closedir( DIR *dirp );

int chdir( const char *path );

char *getcwd( char *buf, size_t size );

int open( const char * path , int oflag , ... );

int creat( const char * path, mode_t mode );

int link( const char *existing, const char *new );

int mkdir( const char *path, mode_t mode );

int unlink( const char *path );

int rmdir( const char *path );

int rename( const char *old, const char *new );

int stat( const char *path, struct stat *buf );

int fstat( int fd, struct stat *buf );

int access( const char *path, int amode );

long pathconf(const char *path, int name);

long fpathconf(int fd, int name);

mode_t umask( mode_t cmask );

int mkfifo( const char *path, mode_t mode );

int chmod( const char *path, mode_t mode );                     // TBA

int fchmod( int fd, mode_t mode );                              // TBA

int chown( const char *path, uid_t owner, gid_t group );

int utime( const char *path, const struct utimbuf *times );     // TBA

int ftruncate( int fd, off_t length );                          // TBA

            If a call to open() or creat() supplies

            the third _mode_ parameter, it will

            currently be ignored.

            Most of the functionality of these functions depends on

            the underlying filesystem.

            Currently access() only checks the

            F_OK mode explicitly, the others are

            all assumed to be true by default.

            The maximum number of open files allowed is supplied by

            the CYGNUM_FILEIO_NFILE option. The maximum number

            of file descriptors is supplied by the CYGNUM_FILEIO_NFD

            option.

int dup( int fd );

int dup2( int fd, int fd2 );

int close(int fd);

ssize_t read(int fd, void *buf, size_t nbyte);

ssize_t write(int fd, const void *buf, size_t nbyte);

int fcntl( int fd, int cmd, ... );

off_t lseek(int fd, off_t offset, int whence);

int fsync( int fd );

int fdatasync( int fd );

int pipe( int fildes[2] );

int aio_read( struct aiocb *aiocbp );                           // TBA

int aio_write( struct aiocb *aiocbp );                          // TBA

int lio_listio( int mode, struct aiocb *const list[],

                int nent, struct sigevent *sig);                // TBA

int aio_error( struct aiocb *aiocbp );                          // TBA

int aio_return( struct aiocb *aiocbp );                         // TBA

int aio_cancel( int fd, struct aiocb *aiocbp );                 // TBA

int aio_suspend( const struct aiocb *const list[],

                 int nent, const struct timespec *timeout );    // TBA

int aio_fsync( int op, struct aiocb *aiocbp );

// TBA

            Only the F_DUPFD command

            of fcntl() is currently implemented.

            Most of the functionality of these functions depends on

            the underlying filesystem.

speed_t cfgetospeed( const struct termios *termios_p );

int cfsetospeed( struct termios *termios_p, speed_t speed );

speed_t cfgetispeed( const struct termios *termios_p );

int cfsetispeed( struct termios *termios_p, speed_t speed );

int tcgetattr( int fd, struct termios *termios_p );

int tcsetattr( int fd, int optional_actions,

               const struct termios *termios_p );

int tcsendbreak( int fd, int duration );

int tcdrain( int fd );

int tcflush( int fd, int queue_selector );

int tcsendbreak( int fd, int action );

pid_t tcgetpgrp( int fd );

int tcsetpgrp( int fd, pid_t pgrp );

            Only the functionality relevant to basic serial device

            control is implemented. Only very limited support for

            canonical input is provided, and then only via the

            “tty” devices, not the “serial”

            devices. None of the functionality relevant to job

            control, controlling terminals and sessions is

            implemented.

            Only MIN = 0 and

            TIME = 0 functionality is

            provided.

            Hardware flow control is supported if the underlying

            device driver and serial port support it.

            Support for break, framing and parity errors depends on

            the functionality of the hardware and device driver.

char *setlocale( int category, const char *locale );

int fileno( FILE *stream );

FILE *fdopen( int fd, const char *type );

int getc_unlocked( FILE *stream);

int getchar_unlocked( void );

int putc_unlocked( FILE *stream );

int putchar_unlocked( void );

char *strtok_r( char *s, const char *sep,

                char **lasts );

char *asctime_r( const struct tm *tm, char *buf );

char *ctime_r( const time_t *clock, char *buf );

struct tm *gmtime_r( const time_t *clock,

                     struct tm *result );

struct tm *localtime_r( const time_t *clock,

                        struct tm *result );

int rand_r( unsigned int *seed );

void flockfile( FILE *file );

int ftrylockfile( FILE *file );

void funlockfile( FILE *file );

int sigsetjmp( sigjmp_buf env, int savemask );                  // TBA

void siglongjmp( sigjmp_buf env, int val );                     // TBA

void tzset(void);                                                       // TBA

            setlocale() is implemented in the C

            library Internationalization package.

            Functions fileno() and

            fdopen() are implemented in the C

            library STDIO package.

            Functions getc_unlocked(),

            getchar_unlocked(),

            putc_unlocked() and

            putchar_unlocked() are defined

            but are currently identical to their non-unlocked

            equivalents.

            strtok_r(), asctime_r(),

            ctime_r(), gmtime_r(),

            localtime_r() and

            rand_r() are all currently in

            the C library, alongside their non-reentrant versions.

<none>

struct group *getgrgid( gid_t gid );

int getgrgid( gid_t gid, struct group *grp, char *buffer,

              size_t bufsize, struct group **result );

struct group *getgrname( const char *name );

int getgrname_r( const char *name, struct group *grp,

                 char *buffer, size_t bufsize, struct group **result );

struct passwd *getpwuid( uid_t uid );

int getpwuid_r( uid_t uid, struct passwd *pwd,

                char *buffer, size_t bufsize, struct passwd **result );

struct passwd *getpwnam( const char *name );

int getpwnam_r( const char *name, struct passwd *pwd,

                char *buffer, size_t bufsize, struct passwd **result );

            None of the functions in this section are implemented.

This section details tar and

cpio formats. Neither of these is supported by

eCos.

int sem_init(sem_t *sem, int pshared, unsigned int value);

int sem_destroy(sem_t *sem);

int sem_wait(sem_t *sem);

int sem_trywait(sem_t *sem);

int sem_post(sem_t *sem);

int sem_getvalue(sem_t *sem, int *sval);

int pthread_mutexattr_init( pthread_mutexattr_t *attr);

int pthread_mutexattr_destroy( pthread_mutexattr_t *attr);

int pthread_mutex_init(pthread_mutex_t *mutex,

                       const pthread_mutexattr_t *mutex_attr);

int pthread_mutex_destroy(pthread_mutex_t *mutex);

int pthread_mutex_lock(pthread_mutex_t *mutex);

int pthread_mutex_trylock(pthread_mutex_t *mutex);

int pthread_mutex_unlock(pthread_mutex_t *mutex);

int pthread_condattr_init(pthread_condattr_t *attr);

int pthread_condattr_destroy(pthread_condattr_t *attr);

int pthread_cond_init(pthread_cond_t *cond,

                       const pthread_condattr_t *attr);

int pthread_cond_destroy(pthread_cond_t *cond);

int pthread_cond_signal(pthread_cond_t *cond);

int pthread_cond_broadcast(pthread_cond_t *cond);

int pthread_cond_wait(pthread_cond_t *cond,

                       pthread_mutex_t *mutex);

int pthread_cond_timedwait(pthread_cond_t *cond,

                           pthread_mutex_t *mutex,

                           const struct timespec *abstime);

sem_t *sem_open(const char *name, int oflag, ...);              // TBA

int sem_close(sem_t *sem);                                      // TBA

int sem_unlink(const char *name);                               // TBA

int pthread_mutexattr_getpshared( const pthread_mutexattr_t *attr,

                                  int *pshared );

int pthread_mutexattr_setpshared( const pthread_mutexattr_t *attr,

                                  int pshared );

int  pthread_condattr_getpshared( const pthread_condattr_t *attr,

                                  int *pshared);

int  pthread_condattr_setpshared( const pthread_condattr_t *attr,

                                  int pshared);

            The presence of semaphores is controlled by the

            CYGPKG_POSIX_SEMAPHORES option. This in turn

            causes the _POSIX_SEMAPHORES feature test

            macro to be defined and the semaphore API to be made

            available.

            The pshared argument to

            sem_init() is not implemented,

            its value is ignored.

            Functions sem_open(),

            sem_close() and

            sem_unlink() are present but

            always return an error (ENOSYS).

            The exact priority inversion protocols supported may be

            controlled with the

            _POSIX_THREAD_PRIO_INHERIT and

            _POSIX_THREAD_PRIO_PROTECT

            configuration options.

            {_POSIX_THREAD_PROCESS_SHARED} is

            not defined, so the

            process-shared mutex

            and condition variable attributes are not supported, and

            neither are the functions

            pthread_mutexattr_getpshared(),

            pthread_mutexattr_setpshared(),

            pthread_condattr_getpshared() and

            pthread_condattr_setpshared().

            Condition variables do not become bound to a particular

            mutex when

            pthread_cond_wait() is

            called. Hence different threads may wait on a condition

            variable with different mutexes. This is at variance with

            the standard, which requires a condition variable to

            become (dynamically) bound by the first waiter, and

            unbound when the last finishes. However, this difference

            is largely benign, and the cost of policing this feature

            is non-trivial.

<none>

int mlockall( int flags );

int munlockall( void );

int mlock( const void *addr, size_t len );

int munlock( const void *addr, size_t len );

void mmap( void *addr, size_t len, int prot, int flags,

           int fd, off_t off );

int munmap( void *addr, size_t len );

int mprotect( const void *addr, size_t len, int prot );

int msync( void *addr, size_t len, int flags );

int shm_open( const char *name, int oflag, mode_t mode );

int shm_unlink( const char *name );

None of these functions are currently provided. Some may

be implemented in a restricted form in the future.

int sched_yield(void);

int sched_get_priority_max(int policy);