RTEMS POSIX API Guide (5.2-rc1).

Copyrights and License

© 2018 Marçal Comajoan Cara

© 2017 Gedare Bloom

© 1988, 2018 On-Line Applications Research Corporation (OAR)

This document is available under the Creative Commons Attribution-ShareAlike 4.0 International Public License.

The authors have used their best efforts in preparing this material. These efforts include the development, research, and testing of the theories and programs to determine their effectiveness. No warranty of any kind, expressed or implied, with regard to the software or the material contained in this document is provided. No liability arising out of the application or use of any product described in this document is assumed. The authors reserve the right to revise this material and to make changes from time to time in the content hereof without obligation to notify anyone of such revision or changes.

The RTEMS Project is hosted at https://www.rtems.org. Any inquiries concerning RTEMS, its related support components, or its documentation should be directed to the RTEMS Project community.

RTEMS Online Resources

Home	https://www.rtems.org
Documentation	https://docs.rtems.org
Mailing Lists	https://lists.rtems.org
Bug Reporting	https://devel.rtems.org/wiki/Developer/Bug_Reporting
Git Repositories	https://git.rtems.org
Developers	https://devel.rtems.org

• 1. Preface
  • 1.1. Acknowledgements
• 2. Process Creation and Execution Manager
  • 2.1. Introduction
  • 2.2. Background
  • 2.3. Operations
  • 2.4. Directives
    • 2.4.1. fork - Create a Process
    • 2.4.2. execl - Execute a File
    • 2.4.3. execv - Execute a File
    • 2.4.4. execle - Execute a File
    • 2.4.5. execve - Execute a File
    • 2.4.6. execlp - Execute a File
    • 2.4.7. execvp - Execute a File
    • 2.4.8. pthread_atfork - Register Fork Handlers
    • 2.4.9. wait - Wait for Process Termination
    • 2.4.10. waitpid - Wait for Process Termination
    • 2.4.11. _exit - Terminate a Process
• 3. Signal Manager
  • 3.1. Introduction
  • 3.2. Background
    • 3.2.1. Signals
    • 3.2.2. Signal Delivery
  • 3.3. Operations
    • 3.3.1. Signal Set Management
    • 3.3.2. Blocking Until Signal Generation
    • 3.3.3. Sending a Signal
  • 3.4. Directives
    • 3.4.1. sigaddset - Add a Signal to a Signal Set
    • 3.4.2. sigdelset - Delete a Signal from a Signal Set
    • 3.4.3. sigfillset - Fill a Signal Set
    • 3.4.4. sigismember - Is Signal a Member of a Signal Set
    • 3.4.5. sigemptyset - Empty a Signal Set
    • 3.4.6. sigaction - Examine and Change Signal Action
    • 3.4.7. pthread_kill - Send a Signal to a Thread
    • 3.4.8. sigprocmask - Examine and Change Process Blocked Signals
    • 3.4.9. pthread_sigmask - Examine and Change Thread Blocked Signals
    • 3.4.10. kill - Send a Signal to a Process
    • 3.4.11. sigpending - Examine Pending Signals
    • 3.4.12. sigsuspend - Wait for a Signal
    • 3.4.13. pause - Suspend Process Execution
    • 3.4.14. sigwait - Synchronously Accept a Signal
    • 3.4.15. sigwaitinfo - Synchronously Accept a Signal
    • 3.4.16. sigtimedwait - Synchronously Accept a Signal with Timeout
    • 3.4.17. sigqueue - Queue a Signal to a Process
    • 3.4.18. alarm - Schedule Alarm
    • 3.4.19. ualarm - Schedule Alarm in Microseconds
• 4. Process Environment Manager
  • 4.1. Introduction
  • 4.2. Background
    • 4.2.1. Users and Groups
    • 4.2.2. User and Group Names
    • 4.2.3. Environment Variables
  • 4.3. Operations
    • 4.3.1. Accessing User and Group Ids
    • 4.3.2. Accessing Environment Variables
  • 4.4. Directives
    • 4.4.1. getpid - Get Process ID
    • 4.4.2. getppid - Get Parent Process ID
    • 4.4.3. getuid - Get User ID
    • 4.4.4. geteuid - Get Effective User ID
    • 4.4.5. getgid - Get Real Group ID
    • 4.4.6. getegid - Get Effective Group ID
    • 4.4.7. setuid - Set User ID
    • 4.4.8. setgid - Set Group ID
    • 4.4.9. getgroups - Get Supplementary Group IDs
    • 4.4.10. getlogin - Get User Name
    • 4.4.11. getlogin_r - Reentrant Get User Name
    • 4.4.12. getpgrp - Get Process Group ID
    • 4.4.13. setsid - Create Session and Set Process Group ID
    • 4.4.14. setpgid - Set Process Group ID for Job Control
    • 4.4.15. uname - Get System Name
    • 4.4.16. times - Get process times
    • 4.4.17. getenv - Get Environment Variables
    • 4.4.18. setenv - Set Environment Variables
    • 4.4.19. ctermid - Generate Terminal Pathname
    • 4.4.20. ttyname - Determine Terminal Device Name
    • 4.4.21. ttyname_r - Reentrant Determine Terminal Device Name
    • 4.4.22. isatty - Determine if File Descriptor is Terminal
    • 4.4.23. sysconf - Get Configurable System Variables
• 5. Files and Directories Manager
  • 5.1. Introduction
  • 5.2. Background
    • 5.2.1. Path Name Evaluation
  • 5.3. Operations
  • 5.4. Directives
    • 5.4.1. opendir - Open a Directory
    • 5.4.2. readdir - Reads a directory
    • 5.4.3. rewinddir - Resets the readdir() pointer
    • 5.4.4. scandir - Scan a directory for matching entries
    • 5.4.5. telldir - Return current location in directory stream
    • 5.4.6. closedir - Ends directory read operation
    • 5.4.7. chdir - Changes the current working directory
    • 5.4.8. fchdir - Changes the current working directory
    • 5.4.9. getcwd - Gets current working directory
    • 5.4.10. open - Opens a file
    • 5.4.11. creat - Create a new file or rewrite an existing one
    • 5.4.12. umask - Sets a file creation mask.
    • 5.4.13. link - Creates a link to a file
    • 5.4.14. symlink - Creates a symbolic link to a file
    • 5.4.15. readlink - Obtain the name of a symbolic link destination
    • 5.4.16. mkdir - Makes a directory
    • 5.4.17. mkfifo - Makes a FIFO special file
    • 5.4.18. unlink - Removes a directory entry
    • 5.4.19. rmdir - Delete a directory
    • 5.4.20. rename - Renames a file
    • 5.4.21. stat - Gets information about a file
    • 5.4.22. fstat - Gets file status
    • 5.4.23. lstat - Gets file status
    • 5.4.24. access - Check permissions for a file
    • 5.4.25. chmod - Changes file mode.
    • 5.4.26. fchmod - Changes permissions of a file
    • 5.4.27. getdents - Get directory entries
    • 5.4.28. chown - Changes the owner and/or group of a file.
    • 5.4.29. utime - Change access and/or modification times of an inode
    • 5.4.30. ftruncate - truncate a file to a specified length
    • 5.4.31. truncate - truncate a file to a specified length
    • 5.4.32. pathconf - Gets configuration values for files
    • 5.4.33. fpathconf - Gets configuration values for files
    • 5.4.34. mknod - create a directory
• 6. Input and Output Primitives Manager
  • 6.1. Introduction
  • 6.2. Background
  • 6.3. Operations
  • 6.4. Directives
    • 6.4.1. pipe - Create an Inter-Process Channel
    • 6.4.2. dup - Duplicates an open file descriptor
    • 6.4.3. dup2 - Duplicates an open file descriptor
    • 6.4.4. close - Closes a file
    • 6.4.5. read - Reads from a file
    • 6.4.6. write - Writes to a file
    • 6.4.7. fcntl - Manipulates an open file descriptor
    • 6.4.8. lseek - Reposition read/write file offset
    • 6.4.9. fsync - Synchronize file complete in-core state with that on disk
    • 6.4.10. fdatasync - Synchronize file in-core data with that on disk
    • 6.4.11. sync - Schedule file system updates
    • 6.4.12. mount - Mount a file system
    • 6.4.13. unmount - Unmount file systems
    • 6.4.14. readv - Vectored read from a file
    • 6.4.15. writev - Vectored write to a file
    • 6.4.16. aio_read - Asynchronous Read
    • 6.4.17. aio_write - Asynchronous Write
    • 6.4.18. lio_listio - List Directed I/O
    • 6.4.19. aio_error - Retrieve Error Status of Asynchronous I/O Operation
    • 6.4.20. aio_return - Retrieve Return Status Asynchronous I/O Operation
    • 6.4.21. aio_cancel - Cancel Asynchronous I/O Request
    • 6.4.22. aio_suspend - Wait for Asynchronous I/O Request
    • 6.4.23. aio_fsync - Asynchronous File Synchronization
• 7. Device- and Class- Specific Functions Manager
  • 7.1. Introduction
  • 7.2. Background
  • 7.3. Operations
  • 7.4. Directives
    • 7.4.1. cfgetispeed - Reads terminal input baud rate
    • 7.4.2. cfgetospeed - Reads terminal output baud rate
    • 7.4.3. cfsetispeed - Sets terminal input baud rate
    • 7.4.4. cfsetospeed - Sets terminal output baud rate
    • 7.4.5. tcgetattr - Gets terminal attributes
    • 7.4.6. tcsetattr - Set terminal attributes
    • 7.4.7. tcsendbreak - Sends a break to a terminal
    • 7.4.8. tcdrain - Waits for all output to be transmitted to the terminal.
    • 7.4.9. tcflush - Discards terminal data
    • 7.4.10. tcflow - Suspends/restarts terminal output.
    • 7.4.11. tcgetpgrp - Gets foreground process group ID
    • 7.4.12. tcsetpgrp - Sets foreground process group ID
• 8. Language-Specific Services for the C Programming Language Manager
  • 8.1. Introduction
  • 8.2. Background
  • 8.3. Operations
  • 8.4. Directives
    • 8.4.1. setlocale - Set the Current Locale
    • 8.4.2. fileno - Obtain File Descriptor Number for this File
    • 8.4.3. fdopen - Associate Stream with File Descriptor
    • 8.4.4. flockfile - Acquire Ownership of File Stream
    • 8.4.5. ftrylockfile - Poll to Acquire Ownership of File Stream
    • 8.4.6. funlockfile - Release Ownership of File Stream
    • 8.4.7. getc_unlocked - Get Character without Locking
    • 8.4.8. getchar_unlocked - Get Character from stdin without Locking
    • 8.4.9. putc_unlocked - Put Character without Locking
    • 8.4.10. putchar_unlocked - Put Character to stdin without Locking
    • 8.4.11. setjmp - Save Context for Non-Local Goto
    • 8.4.12. longjmp - Non-Local Jump to a Saved Context
    • 8.4.13. sigsetjmp - Save Context with Signal Status for Non-Local Goto
    • 8.4.14. siglongjmp - Non-Local Jump with Signal Status to a Saved Context
    • 8.4.15. tzset - Initialize Time Conversion Information
    • 8.4.16. strtok_r - Reentrant Extract Token from String
    • 8.4.17. asctime_r - Reentrant struct tm to ASCII Time Conversion
    • 8.4.18. ctime_r - Reentrant time_t to ASCII Time Conversion
    • 8.4.19. gmtime_r - Reentrant UTC Time Conversion
    • 8.4.20. localtime_r - Reentrant Local Time Conversion
    • 8.4.21. rand_r - Reentrant Random Number Generation
• 9. System Databases Manager
  • 9.1. Introduction
  • 9.2. Background
  • 9.3. Operations
  • 9.4. Directives
    • 9.4.1. getgrgid - Get Group File Entry for ID
    • 9.4.2. getgrgid_r - Reentrant Get Group File Entry
    • 9.4.3. getgrnam - Get Group File Entry for Name
    • 9.4.4. getgrnam_r - Reentrant Get Group File Entry for Name
    • 9.4.5. getpwuid - Get Password File Entry for UID
    • 9.4.6. getpwuid_r - Reentrant Get Password File Entry for UID
    • 9.4.7. getpwnam - Password File Entry for Name
    • 9.4.8. getpwnam_r - Reentrant Get Password File Entry for Name
• 10. Semaphore Manager
  • 10.1. Introduction
  • 10.2. Background
    • 10.2.1. Theory
    • 10.2.2. “sem_t” Structure
    • 10.2.3. Building a Semaphore Attribute Set
  • 10.3. Operations
    • 10.3.1. Using as a Binary Semaphore
  • 10.4. Directives
    • 10.4.1. sem_init - Initialize an unnamed semaphore
    • 10.4.2. sem_destroy - Destroy an unnamed semaphore
    • 10.4.3. sem_open - Open a named semaphore
    • 10.4.4. sem_close - Close a named semaphore
    • 10.4.5. sem_unlink - Unlink a semaphore
    • 10.4.6. sem_wait - Wait on a Semaphore
    • 10.4.7. sem_trywait - Non-blocking Wait on a Semaphore
    • 10.4.8. sem_timedwait - Wait on a Semaphore for a Specified Time
    • 10.4.9. sem_post - Unlock a Semaphore
    • 10.4.10. sem_getvalue - Get the value of a semaphore
• 11. Mutex Manager
  • 11.1. Introduction
  • 11.2. Background
    • 11.2.1. Mutex Attributes
    • 11.2.2. PTHREAD_MUTEX_INITIALIZER
  • 11.3. Operations
  • 11.4. Services
    • 11.4.1. pthread_mutexattr_init - Initialize a Mutex Attribute Set
    • 11.4.2. pthread_mutexattr_destroy - Destroy a Mutex Attribute Set
    • 11.4.3. pthread_mutexattr_setprotocol - Set the Blocking Protocol
    • 11.4.4. pthread_mutexattr_getprotocol - Get the Blocking Protocol
    • 11.4.5. pthread_mutexattr_setprioceiling - Set the Priority Ceiling
    • 11.4.6. pthread_mutexattr_getprioceiling - Get the Priority Ceiling
    • 11.4.7. pthread_mutexattr_setpshared - Set the Visibility
    • 11.4.8. pthread_mutexattr_getpshared - Get the Visibility
    • 11.4.9. pthread_mutex_init - Initialize a Mutex
    • 11.4.10. pthread_mutex_destroy - Destroy a Mutex
    • 11.4.11. pthread_mutex_lock - Lock a Mutex
    • 11.4.12. pthread_mutex_trylock - Poll to Lock a Mutex
    • 11.4.13. pthread_mutex_timedlock - Lock a Mutex with Timeout
    • 11.4.14. pthread_mutex_unlock - Unlock a Mutex
    • 11.4.15. pthread_mutex_setprioceiling - Dynamically Set the Priority Ceiling
    • 11.4.16. pthread_mutex_getprioceiling - Get the Current Priority Ceiling
• 12. Condition Variable Manager
  • 12.1. Introduction
  • 12.2. Background
  • 12.3. Operations
  • 12.4. Directives
    • 12.4.1. pthread_condattr_init - Initialize a Condition Variable Attribute Set
    • 12.4.2. pthread_condattr_destroy - Destroy a Condition Variable Attribute Set
    • 12.4.3. pthread_condattr_setpshared - Set Process Shared Attribute
    • 12.4.4. pthread_condattr_getpshared - Get Process Shared Attribute
    • 12.4.5. pthread_cond_init - Initialize a Condition Variable
    • 12.4.6. pthread_cond_destroy - Destroy a Condition Variable
    • 12.4.7. pthread_cond_signal - Signal a Condition Variable
    • 12.4.8. pthread_cond_broadcast - Broadcast a Condition Variable
    • 12.4.9. pthread_cond_wait - Wait on a Condition Variable
    • 12.4.10. pthread_cond_timedwait - Wait with Timeout a Condition Variable
• 13. Memory Management Manager
  • 13.1. Introduction
  • 13.2. Background
  • 13.3. Operations
  • 13.4. Directives
    • 13.4.1. mlockall - Lock the Address Space of a Process
    • 13.4.2. munlockall - Unlock the Address Space of a Process
    • 13.4.3. mlock - Lock a Range of the Process Address Space
    • 13.4.4. munlock - Unlock a Range of the Process Address Space
    • 13.4.5. mmap - Map Process Addresses to a Memory Object
    • 13.4.6. munmap - Unmap Previously Mapped Addresses
    • 13.4.7. mprotect - Change Memory Protection
    • 13.4.8. msync - Memory Object Synchronization
    • 13.4.9. shm_open - Open a Shared Memory Object
    • 13.4.10. shm_unlink - Remove a Shared Memory Object
• 14. Scheduler Manager
  • 14.1. Introduction
  • 14.2. Background
    • 14.2.1. Priority
    • 14.2.2. Scheduling Policies
  • 14.3. Operations
  • 14.4. Directives
    • 14.4.1. sched_get_priority_min - Get Minimum Priority Value
    • 14.4.2. sched_get_priority_max - Get Maximum Priority Value
    • 14.4.3. sched_rr_get_interval - Get Timeslicing Quantum
    • 14.4.4. sched_yield - Yield the Processor
• 15. Clock Manager
  • 15.1. Introduction
  • 15.2. Background
  • 15.3. Operations
  • 15.4. Directives
    • 15.4.1. clock_gettime - Obtain Time of Day
    • 15.4.2. clock_settime - Set Time of Day
    • 15.4.3. clock_getres - Get Clock Resolution
    • 15.4.4. sleep - Delay Process Execution
    • 15.4.5. usleep - Delay Process Execution in Microseconds
    • 15.4.6. nanosleep - Delay with High Resolution
    • 15.4.7. gettimeofday - Get the Time of Day
    • 15.4.8. time - Get time in seconds
• 16. Timer Manager
  • 16.1. Introduction
  • 16.2. Background
  • 16.3. Operations
  • 16.4. System Calls
    • 16.4.1. timer_create - Create a Per-Process Timer
    • 16.4.2. timer_delete - Delete a Per-Process Timer
    • 16.4.3. timer_settime - Set Next Timer Expiration
    • 16.4.4. timer_gettime - Get Time Remaining on Timer
    • 16.4.5. timer_getoverrun - Get Timer Overrun Count
• 17. Message Passing Manager
  • 17.1. Introduction
  • 17.2. Background
    • 17.2.1. Theory
    • 17.2.2. Messages
    • 17.2.3. Message Queues
    • 17.2.4. Building a Message Queue Attribute Set
    • 17.2.5. Notification of a Message on the Queue
    • 17.2.6. POSIX Interpretation Issues
  • 17.3. Operations
    • 17.3.1. Opening or Creating a Message Queue
    • 17.3.2. Closing a Message Queue
    • 17.3.3. Removing a Message Queue
    • 17.3.4. Sending a Message to a Message Queue
    • 17.3.5. Receiving a Message from a Message Queue
    • 17.3.6. Notification of Receipt of a Message on an Empty Queue
    • 17.3.7. Setting the Attributes of a Message Queue
    • 17.3.8. Getting the Attributes of a Message Queue
  • 17.4. Directives
    • 17.4.1. mq_open - Open a Message Queue
    • 17.4.2. mq_close - Close a Message Queue
    • 17.4.3. mq_unlink - Remove a Message Queue
    • 17.4.4. mq_send - Send a Message to a Message Queue
    • 17.4.5. mq_receive - Receive a Message from a Message Queue
    • 17.4.6. mq_notify - Notify Process that a Message is Available
    • 17.4.7. mq_setattr - Set Message Queue Attributes
    • 17.4.8. mq_getattr - Get Message Queue Attributes
• 18. Thread Manager
  • 18.1. Introduction
  • 18.2. Background
    • 18.2.1. Thread Attributes
  • 18.3. Operations
  • 18.4. Services
    • 18.4.1. pthread_attr_init - Initialize a Thread Attribute Set
    • 18.4.2. pthread_attr_destroy - Destroy a Thread Attribute Set
    • 18.4.3. pthread_attr_setdetachstate - Set Detach State
    • 18.4.4. pthread_attr_getdetachstate - Get Detach State
    • 18.4.5. pthread_attr_setstacksize - Set Thread Stack Size
    • 18.4.6. pthread_attr_getstacksize - Get Thread Stack Size
    • 18.4.7. pthread_attr_setstackaddr - Set Thread Stack Address
    • 18.4.8. pthread_attr_getstackaddr - Get Thread Stack Address
    • 18.4.9. pthread_attr_setscope - Set Thread Scheduling Scope
    • 18.4.10. pthread_attr_getscope - Get Thread Scheduling Scope
    • 18.4.11. pthread_attr_setinheritsched - Set Inherit Scheduler Flag
    • 18.4.12. pthread_attr_getinheritsched - Get Inherit Scheduler Flag
    • 18.4.13. pthread_attr_setschedpolicy - Set Scheduling Policy
    • 18.4.14. pthread_attr_getschedpolicy - Get Scheduling Policy
    • 18.4.15. pthread_attr_setschedparam - Set Scheduling Parameters
    • 18.4.16. pthread_attr_getschedparam - Get Scheduling Parameters
    • 18.4.17. pthread_attr_getaffinity_np - Get Thread Affinity Attribute
    • 18.4.18. pthread_attr_setaffinity_np - Set Thread Affinity Attribute
    • 18.4.19. pthread_create - Create a Thread
    • 18.4.20. pthread_exit - Terminate the Current Thread
    • 18.4.21. pthread_detach - Detach a Thread
    • 18.4.22. pthread_getconcurrency - Obtain Thread Concurrency
    • 18.4.23. pthread_setconcurrency - Set Thread Concurrency
    • 18.4.24. pthread_getattr_np - Get Thread Attributes
    • 18.4.25. pthread_join - Wait for Thread Termination
    • 18.4.26. pthread_self - Get Thread ID
    • 18.4.27. pthread_equal - Compare Thread IDs
    • 18.4.28. pthread_once - Dynamic Package Initialization
    • 18.4.29. pthread_setschedparam - Set Thread Scheduling Parameters
    • 18.4.30. pthread_getschedparam - Get Thread Scheduling Parameters
    • 18.4.31. pthread_getaffinity_np - Get Thread Affinity
    • 18.4.32. pthread_setaffinity_np - Set Thread Affinity
• 19. Key Manager
  • 19.1. Introduction
  • 19.2. Background
  • 19.3. Operations
  • 19.4. Directives
    • 19.4.1. pthread_key_create - Create Thread Specific Data Key
    • 19.4.2. pthread_key_delete - Delete Thread Specific Data Key
    • 19.4.3. pthread_setspecific - Set Thread Specific Key Value
    • 19.4.4. pthread_getspecific - Get Thread Specific Key Value
• 20. Thread Cancellation Manager
  • 20.1. Introduction
  • 20.2. Background
  • 20.3. Operations
  • 20.4. Directives
    • 20.4.1. pthread_cancel - Cancel Execution of a Thread
    • 20.4.2. pthread_setcancelstate - Set Cancelability State
    • 20.4.3. pthread_setcanceltype - Set Cancelability Type
    • 20.4.4. pthread_testcancel - Create Cancellation Point
    • 20.4.5. pthread_cleanup_push - Establish Cancellation Handler
    • 20.4.6. pthread_cleanup_pop - Remove Cancellation Handler
• 21. Services Provided by C Library (libc)
  • 21.1. Introduction
  • 21.2. Standard Utility Functions (stdlib.h)
  • 21.3. Character Type Macros and Functions (ctype.h)
  • 21.4. Input and Output (stdio.h)
  • 21.5. Strings and Memory (string.h)
  • 21.6. Signal Handling (signal.h)
  • 21.7. Time Functions (time.h)
  • 21.8. Locale (locale.h)
  • 21.9. Reentrant Versions of Functions
  • 21.10. Miscellaneous Macros and Functions
  • 21.11. Variable Argument Lists
  • 21.12. Reentrant System Calls
• 22. Services Provided by the Math Library (libm)
  • 22.1. Introduction
  • 22.2. Standard Math Functions (math.h)
• 23. Device Control
  • 23.1. Introduction
  • 23.2. Background
  • 23.3. Operations
  • 23.4. System Calls
    • 23.4.1. posix_devctl - Control a Device
• 24. Status of Implementation
• 25. Command and Variable Index