RTEMS POSIX API Guide (6.9e8141c).¶

2.4.1. fork - Create a Process¶

CALLING SEQUENCE:

#include <sys/types.h>
int fork( void );

STATUS CODES:

DESCRIPTION:

This routine is not supported by RTEMS.

NOTES:

NONE

2.4.2. execl - Execute a File¶

CALLING SEQUENCE:

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

STATUS CODES:

DESCRIPTION:

This routine is not supported by RTEMS.

NOTES:

NONE

2.4.3. execv - Execute a File¶

CALLING SEQUENCE:

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

STATUS CODES:

DESCRIPTION:

This routine is not supported by RTEMS.

NOTES:

NONE

2.4.4. execle - Execute a File¶

CALLING SEQUENCE:

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

STATUS CODES:

DESCRIPTION:

This routine is not supported by RTEMS.

NOTES:

NONE

2.4.5. execve - Execute a File¶

CALLING SEQUENCE:

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

STATUS CODES:

DESCRIPTION:

This routine is not supported by RTEMS.

NOTES:

NONE

2.4.6. execlp - Execute a File¶

CALLING SEQUENCE:

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

STATUS CODES:

DESCRIPTION:

This routine is not supported by RTEMS.

NOTES:

NONE

2.4.7. execvp - Execute a File¶

CALLING SEQUENCE:

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

STATUS CODES:

DESCRIPTION:

This routine is not supported by RTEMS.

NOTES:

NONE

2.4.8. pthread_atfork - Register Fork Handlers¶

CALLING SEQUENCE:

#include <sys/types.h>
int pthread_atfork(
    void (*prepare)(void),
    void (*parent)(void),
    void (*child)(void)
);

STATUS CODES:

DESCRIPTION:

This routine is non-functional stub.

NOTES:

The POSIX specification for pthread_atfork() does not address the behavior when in a single process environment. Originally, the RTEMS implementation returned -1 and set errno to ENOSYS. This was an arbitrary decision part with no basis from the wider POSIX community. The FACE Technical Standard includes profiles without multiple process support and defined the behavior in a single process environment to return 0. Logically, the application can register atfork handlers but they will never be invoked.

2.4.9. wait - Wait for Process Termination¶

CALLING SEQUENCE:

#include <sys/types.h>
#include <sys/wait.h>
int wait(
    int *stat_loc
);

STATUS CODES:

DESCRIPTION:

This routine is not supported by RTEMS.

NOTES:

NONE

2.4.10. waitpid - Wait for Process Termination¶

CALLING SEQUENCE:

int wait(
    pid_t  pid,
    int   *stat_loc,
    int    options
);

STATUS CODES:

DESCRIPTION:

This routine is not supported by RTEMS.

NOTES:

NONE

2.4.11. _exit - Terminate a Process¶

CALLING SEQUENCE:

void _exit(
    int status
);

STATUS CODES:

NONE

DESCRIPTION:

The _exit() function terminates the calling process.

NOTES:

In RTEMS, a process is equivalent to the entire application on a single processor. Invoking this service terminates the application.

3.2.1. Signals¶

POSIX signals are an asynchronous event mechanism. Each process and thread has a set of signals associated with it. Individual signals may be enabled (e.g. unmasked) or blocked (e.g. ignored) on both a per-thread and process level. Signals which are enabled have a signal handler associated with them. When the signal is generated and conditions are met, then the signal handler is invoked in the proper process or thread context asynchronous relative to the logical thread of execution.

If a signal has been blocked when it is generated, then it is queued and kept pending until the thread or process unblocks the signal or explicitly checks for it. Traditional, non-real-time POSIX signals do not queue. Thus if a process or thread has blocked a particular signal, then multiple occurrences of that signal are recorded as a single occurrence of that signal.

One can check for the set of outstanding signals that have been blocked. Services are provided to check for outstanding process or thread directed signals.

3.2.2. Signal Delivery¶

Signals which are directed at a thread are delivered to the specified thread.

Signals which are directed at a process are delivered to a thread which is selected based on the following algorithm:

1. If the action for this signal is currently SIG_IGN, then the signal is simply ignored.

2. If the currently executing thread has the signal unblocked, then the signal is delivered to it.

3. If any threads are currently blocked waiting for this signal (sigwait()), then the signal is delivered to the highest priority thread waiting for this signal.

4. If any other threads are willing to accept delivery of the signal, then the signal is delivered to the highest priority thread of this set. In the event, multiple threads of the same priority are willing to accept this signal, then priority is given first to ready threads, then to threads blocked on calls which may be interrupted, and finally to threads blocked on non-interruptible calls.

5. In the event the signal still can not be delivered, then it is left pending. The first thread to unblock the signal (sigprocmask() or pthread_sigprocmask()) or to wait for this signal (sigwait()) will be the recipient of the signal.

3.3.1. Signal Set Management¶

Each process and each thread within that process has a set of individual signals and handlers associated with it. Services are provided to construct signal sets for the purposes of building signal sets - type sigset_t - that are used to provide arguments to the services that mask, unmask, and check on pending signals.

3.3.2. Blocking Until Signal Generation¶

A thread may block until receipt of a signal. The “sigwait” and “pause” families of functions block until the requested signal is received or if using sigtimedwait() until the specified timeout period has elapsed.

3.3.3. Sending a Signal¶

This is accomplished via one of a number of services that sends a signal to either a process or thread. Signals may be directed at a process by the service kill() or at a thread by the service pthread_kill()

3.4.1. sigaddset - Add a Signal to a Signal Set¶

CALLING SEQUENCE:

#include <signal.h>
int sigaddset(
    sigset_t *set,
    int       signo
);

STATUS CODES:

The function returns 0 on success, otherwise it returns -1 and sets errno to indicate the error. errno may be set to:

DESCRIPTION:

This function adds the signal signo to the specified signal set.

NOTES:

The set must be initialized using either sigemptyset or sigfillset before using this function.

3.4.2. sigdelset - Delete a Signal from a Signal Set¶

CALLING SEQUENCE:

#include <signal.h>
int sigdelset(
    sigset_t *set,
    int       signo
);

STATUS CODES:

The function returns 0 on success, otherwise it returns -1 and sets errno to indicate the error. errno may be set to:

DESCRIPTION:

This function deletes the signal specified by signo from the specified signal set.

NOTES:

The set must be initialized using either sigemptyset or sigfillset before using this function.

3.4.3. sigfillset - Fill a Signal Set¶

CALLING SEQUENCE:

#include <signal.h>
int sigfillset(
    sigset_t *set
);

STATUS CODES:

The function returns 0 on success, otherwise it returns -1 and sets errno to indicate the error. errno may be set to:

DESCRIPTION:

This function fills the specified signal set such that all signals are set.

3.4.4. sigismember - Is Signal a Member of a Signal Set¶

CALLING SEQUENCE:

#include <signal.h>
int sigismember(
    const sigset_t *set,
    int             signo
);

STATUS CODES:

The function returns either 1 or 0 if completed successfully, otherwise it returns -1 and sets errno to indicate the error. errno may be set to:

DESCRIPTION:

This function returns returns 1 if signo is a member of set and 0 otherwise.

NOTES:

The set must be initialized using either sigemptyset or sigfillset before using this function.

3.4.5. sigemptyset - Empty a Signal Set¶

CALLING SEQUENCE:

#include <signal.h>
int sigemptyset(
    sigset_t *set
);

STATUS CODES:

The function returns 0 on success, otherwise it returns -1 and sets errno to indicate the error. errno may be set to:

DESCRIPTION:

This function initializes an empty signal set pointed to by set.

3.4.6. sigaction - Examine and Change Signal Action¶

CALLING SEQUENCE:

#include <signal.h>
int sigaction(
    int                     sig,
    const struct sigaction *act,
    struct sigaction       *oact
);

STATUS CODES:

The function returns 0 on success, otherwise it returns -1 and sets errno to indicate the error. errno may be set to:

DESCRIPTION:

If the argument act is not a null pointer, it points to a structure specifying the action to be associated with the specified signal. If the argument oact is not a null pointer, the action previously associated with the signal is stored in the location pointed to by the argument oact. If the argument act is a null pointer, signal handling is unchanged; thus, the call can be used to enquire about the current handling of a given signal.

The structure sigaction has the following members:

sa_handler and sa_sigaction should never be used at the same time as their storage may overlap.

If the SA_SIGINFO flag (see below) is set in sa_flags, the sa_sigaction field specifies a signal-catching function, otherwise``sa_handler`` specifies the action to be associated with the signal, which may be a signal-catching function or one of the macros SIG_IGN or SIG_DFN.

The following flags can be set in the sa_flags field:

The prototype of the siginfo_t structure is the following:

typedef struct
{
    int si_signo;        /* Signal number */
    int si_code;         /* Cause of the signal */
    union sigval
    {
        int sival_int;   /* Integer signal value */
        void* sival_ptr; /* Pointer signal value */
    } si_value;          /* Signal value */
} siginfo_t;

NOTES:

The signal number cannot be SIGKILL.

3.4.7. pthread_kill - Send a Signal to a Thread¶

CALLING SEQUENCE:

#include <signal.h>
int pthread_kill(
    pthread_t thread,
    int       sig
);

STATUS CODES:

The function returns 0 on success, otherwise it returns -1 and sets errno to indicate the error. errno may be set to:

DESCRIPTION:

This functions sends the specified signal sig to a thread referenced to by thread.

If the signal code is 0, arguments are validated and no signal is sent.

3.4.8. sigprocmask - Examine and Change Process Blocked Signals¶

CALLING SEQUENCE:

#include <signal.h>
int sigprocmask(
    int             how,
    const sigset_t *set,
    sigset_t       *oset
);

STATUS CODES:

The function returns 0 on success, otherwise it returns -1 and sets errno to indicate the error. errno may be set to:

DESCRIPTION:

This function is used to alter the set of currently blocked signals on a process wide basis. A blocked signal will not be received by the process. The behavior of this function is dependent on the value of how which may be one of the following:

If oset is not NULL, then the set of blocked signals prior to this call is returned in oset. If set is NULL, no change is done, allowing to examine the set of currently blocked signals.

NOTES:

It is not an error to unblock a signal which is not blocked.

In the current implementation of RTEMS POSIX API sigprocmask() is technically mapped to pthread_sigmask().

3.4.9. pthread_sigmask - Examine and Change Thread Blocked Signals¶

CALLING SEQUENCE:

#include <signal.h>
int pthread_sigmask(
int             how,
const sigset_t *set,
sigset_t       *oset
);

STATUS CODES:

The function returns 0 on success, otherwise it returns -1 and sets errno to indicate the error. errno may be set to:

EINVAL

Invalid argument passed.

DESCRIPTION:

This function is used to alter the set of currently blocked signals for the calling thread. A blocked signal will not be received by the process. The behavior of this function is dependent on the value of how which may be one of the following:

If oset is not NULL, then the set of blocked signals prior to this call is returned in oset. If set is NULL, no change is done, allowing to examine the set of currently blocked signals.

NOTES:

It is not an error to unblock a signal which is not blocked.

3.4.10. kill - Send a Signal to a Process¶

CALLING SEQUENCE:

#include <sys/types.h>
#include <signal.h>
int kill(
    pid_t pid,
    int   sig
);

STATUS CODES:

The function returns 0 on success, otherwise it returns -1 and sets errno to indicate the error. errno may be set to:

DESCRIPTION:

This function sends the signal sig to the process pid.

NOTES:

Since RTEMS is a single-process system, a signal can only be sent to the calling process (i.e. the current node).

3.4.11. sigpending - Examine Pending Signals¶

CALLING SEQUENCE:

#include <signal.h>
    int sigpending(
    const sigset_t *set
);

STATUS CODES:

The function returns 0 on success, otherwise it returns -1 and sets errno to indicate the error. errno may be set to:

DESCRIPTION:

This function allows the caller to examine the set of currently pending signals. A pending signal is one which has been raised but is currently blocked. The set of pending signals is returned in set.

3.4.12. sigsuspend - Wait for a Signal¶

CALLING SEQUENCE:

#include <signal.h>
   int sigsuspend(
   const sigset_t *sigmask
);

STATUS CODES:

The function returns 0 on success, otherwise it returns -1 and sets errno to indicate the error. errno may be set to:

DESCRIPTION:

This function temporarily replaces the signal mask for the process with that specified by sigmask and blocks the calling thread until a signal is raised.

3.4.13. pause - Suspend Process Execution¶

CALLING SEQUENCE:

#include <signal.h>
int pause( void );

STATUS CODES:

The function returns 0 on success, otherwise it returns -1 and sets errno to indicate the error. errno may be set to:

DESCRIPTION:

This function causes the calling thread to be blocked until an unblocked signal is received.

3.4.14. sigwait - Synchronously Accept a Signal¶

CALLING SEQUENCE:

#include <signal.h>
int sigwait(
    const sigset_t *set,
    int            *sig
);

STATUS CODES:

The function returns 0 on success, otherwise it returns -1 and sets errno to indicate the error. errno may be set to:

DESCRIPTION:

This function selects a pending signal based on the set specified in set, atomically clears it from the set of pending signals, and returns the signal number for that signal in sig.

3.4.15. sigwaitinfo - Synchronously Accept a Signal¶

CALLING SEQUENCE:

#include <signal.h>
int sigwaitinfo(
    const sigset_t *set,
    siginfo_t      *info
);

STATUS CODES:

The function returns 0 on success, otherwise it returns -1 and sets errno to indicate the error. errno may be set to:

EINTR

Signal interrupted this function.

DESCRIPTION:

This function selects a pending signal based on the set specified in set, atomically clears it from the set of pending signals, and returns information about that signal in info.

The prototype of the siginfo_t structure is the following:

typedef struct
{
    int si_signo;        /* Signal number */
    int si_code;         /* Cause of the signal */
    union sigval
    {
        int sival_int;   /* Integer signal value */
        void* sival_ptr; /* Pointer signal value */
    } si_value;          /* Signal value */
} siginfo_t;

3.4.16. sigtimedwait - Synchronously Accept a Signal with Timeout¶

CALLING SEQUENCE:

#include <signal.h>
int sigtimedwait(
    const sigset_t        *set,
    siginfo_t             *info,
    const struct timespec *timeout
);

STATUS CODES:

The function returns 0 on success, otherwise it returns -1 and sets errno to indicate the error. errno may be set to:

DESCRIPTION:

This function selects a pending signal based on the set specified in set, atomically clears it from the set of pending signals, and returns information about that signal in info. The calling thread will block up to timeout waiting for the signal to arrive.

The timespec structure is defined as follows:

struct timespec
{
    time_t tv_sec; /* Seconds */
    long tv_nsec;  /* Nanoseconds */
};

NOTES:

If timeout is NULL, then the calling thread will wait forever for the specified signal set.

3.4.17. sigqueue - Queue a Signal to a Process¶

CALLING SEQUENCE:

#include <signal.h>
int sigqueue(
    pid_t              pid,
    int                signo,
    const union sigval value
);

STATUS CODES:

The function returns 0 on success, otherwise it returns -1 and sets errno to indicate the error. errno may be set to:

DESCRIPTION:

This function sends the signal specified by signo to the process pid

The sigval union is specified as:

union sigval
{
    int sival_int; /* Integer signal value */
    void* sival_ptr; /* Pointer signal value */
};

NOTES:

Since RTEMS is a single-process system, a signal can only be sent to the calling process (i.e. the current node).

3.4.18. alarm - Schedule Alarm¶

CALLING SEQUENCE:

#include <unistd.h>
unsigned int alarm(
    unsigned int seconds
);

STATUS CODES:

This call always succeeds.

If there was a previous alarm() request with time remaining, then this routine returns the number of seconds until that outstanding alarm would have fired. If no previous alarm() request was outstanding, then zero is returned.

DESCRIPTION:

The alarm() service causes the SIGALRM signal to be generated after the number of seconds specified by seconds has elapsed.

NOTES:

Alarm requests do not queue. If alarm is called while a previous request is outstanding, the call will result in rescheduling the time at which the SIGALRM signal will be generated.

If the notification signal, SIGALRM, is not caught or ignored, the calling process is terminated.

3.4.19. ualarm - Schedule Alarm in Microseconds¶

CALLING SEQUENCE:

#include <unistd.h>
useconds_t ualarm(
    useconds_t useconds,
    useconds_t interval
);

STATUS CODES:

This call always succeeds.

If there was a previous ualarm() request with time remaining, then this routine returns the number of seconds until that outstanding alarm would have fired. If no previous alarm() request was outstanding, then zero is returned.

DESCRIPTION:

The ualarm() service causes the SIGALRM signal to be generated after the number of microseconds specified by useconds has elapsed.

When interval is non-zero, repeated timeout notification occurs with a period in microseconds specified by interval.

NOTES:

Alarm requests do not queue. If alarm is called while a previous request is outstanding, the call will result in rescheduling the time at which the SIGALRM signal will be generated.

If the notification signal, SIGALRM, is not caught or ignored, the calling process is terminated.

4.2.1. Users and Groups¶

RTEMS provides a single process, multi-threaded execution environment. In this light, the notion of user and group is somewhat without meaning. But RTEMS does provide services to provide a synthetic version of user and group. By default, a single user and group is associated with the application. Thus unless special actions are taken, every thread in the application shares the same user and group Id. The initial rationale for providing user and group Id functionality in RTEMS was for the filesystem infrastructure to implement file permission checks. The effective user/group Id capability has since been used to implement permissions checking by the ftpd server.

In addition to the “real” user and group Ids, a process may have an effective user/group Id. This allows a process to function using a more limited permission set for certain operations.

4.2.2. User and Group Names¶

POSIX considers user and group Ids to be a unique integer that may be associated with a name. This is usually accomplished via a file named /etc/passwd for user Id mapping and /etc/groups for group Id mapping. Again, although RTEMS is effectively a single process and thus single user system, it provides limited support for user and group names. When configured with an appropriate filesystem, RTEMS will access the appropriate files to map user and group Ids to names.

If these files do not exist, then RTEMS will synthesize a minimal version so this family of services return without error. It is important to remember that a design goal of the RTEMS POSIX services is to provide useable and meaningful results even though a full process model is not available.

4.2.3. Environment Variables¶

POSIX allows for variables in the run-time environment. These are name/value pairs that make be dynamically set and obtained by programs. In a full POSIX environment with command line shell and multiple processes, environment variables may be set in one process - such as the shell - and inherited by child processes. In RTEMS, there is only one process and thus only one set of environment variables across all processes.

4.3.1. Accessing User and Group Ids¶

The user Id associated with the current thread may be obtain using the getuid() service. Similarly, the group Id may be obtained using the getgid() service.

4.3.2. Accessing Environment Variables¶

The value associated with an environment variable may be obtained using the getenv() service and set using the putenv() service.

4.4.1. getpid - Get Process ID¶

CALLING SEQUENCE:

int getpid( void );

STATUS CODES:

The process Id is returned.

DESCRIPTION:

This service returns the process Id.

NOTES:

NONE

4.4.2. getppid - Get Parent Process ID¶

CALLING SEQUENCE:

int getppid( void );

STATUS CODES:

The parent process Id is returned.

DESCRIPTION:

This service returns the parent process Id.

NOTES:

NONE

4.4.3. getuid - Get User ID¶

CALLING SEQUENCE:

int getuid( void );

STATUS CODES:

The effective user Id is returned.

DESCRIPTION:

This service returns the effective user Id.

NOTES:

NONE

4.4.4. geteuid - Get Effective User ID¶

CALLING SEQUENCE:

int geteuid( void );

STATUS CODES:

The effective group Id is returned.

DESCRIPTION:

This service returns the effective group Id.

NOTES:

NONE

4.4.5. getgid - Get Real Group ID¶

CALLING SEQUENCE:

int getgid( void );

STATUS CODES:

The group Id is returned.

DESCRIPTION:

This service returns the group Id.

NOTES:

NONE

4.4.6. getegid - Get Effective Group ID¶

CALLING SEQUENCE:

int getegid( void );

STATUS CODES:

The effective group Id is returned.

DESCRIPTION:

This service returns the effective group Id.

NOTES:

NONE

4.4.7. setuid - Set User ID¶

CALLING SEQUENCE:

int setuid(
    uid_t uid
);

STATUS CODES:

This service returns 0.

DESCRIPTION:

This service sets the user Id to uid.

NOTES:

NONE

4.4.8. setgid - Set Group ID¶

CALLING SEQUENCE:

int setgid(
    gid_t  gid
);

STATUS CODES:

This service returns 0.

DESCRIPTION:

This service sets the group Id to gid.

NOTES:

NONE

4.4.9. getgroups - Get Supplementary Group IDs¶

CALLING SEQUENCE:

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

STATUS CODES:

NA

DESCRIPTION:

This service is not implemented as RTEMS has no notion of supplemental groups.

NOTES:

If supported, this routine would only be allowed for the super-user.

4.4.10. getlogin - Get User Name¶

CALLING SEQUENCE:

char *getlogin( void );

STATUS CODES:

Returns a pointer to a string containing the name of the current user.

DESCRIPTION:

This routine returns the name of the current user.

NOTES:

This routine is not reentrant and subsequent calls to getlogin() will overwrite the same buffer.

4.4.11. getlogin_r - Reentrant Get User Name¶

CALLING SEQUENCE:

int getlogin_r(
    char   *name,
    size_t  namesize
);

STATUS CODES:

DESCRIPTION:

This is a reentrant version of the getlogin() service. The caller specified their own buffer, name, as well as the length of this buffer, namesize.

NOTES:

NONE

4.4.12. getpgrp - Get Process Group ID¶

CALLING SEQUENCE:

pid_t getpgrp( void );

STATUS CODES:

The procress group Id is returned.

DESCRIPTION:

This service returns the current progress group Id.

NOTES:

This routine is implemented in a somewhat meaningful way for RTEMS but is truly not functional.

4.4.13. getrusage - Get Resource Utilization¶

CALLING SEQUENCE:

int getrusage( int who, struct rusage *rusage );

STATUS CODES:

Returns the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error.

DESCRIPTION:

This function provides a measures of the resources being used by RTEMS. RTEMS is a single process environment so child process requests result in an error being returned.

A who value of RUSAGE_SELF results in the struct rusage field ru_utime returning the total active time of all threads that exist when the call is made and the field ru_stime returning the total idle time.

A who value of RUSAGE_THREAD results in the struct rusage field ru_utime returning the total active time of the current thread and the field ru_stime is set to 0.

NOTES:

The time returned can be more than the system up time if there is more than one CPU.

This routine is implemented using the internal thread iterator and accounts for time spent by the currently active threads. RTEMS does not account for the execution time of threads that are no longer running.

The idle time is the total time spent in IDLE since RTEMS started. The time for each CPU is summed.

The ratio of the difference between samples made by getrusage of the user and system idle time can be used to compute the current load.

4.4.14. setsid - Create Session and Set Process Group ID¶

CALLING SEQUENCE:

pid_t setsid( void );

STATUS CODES:

DESCRIPTION:

This routine always returns EPERM as RTEMS has no way to create new processes and thus no way to create a new process group.

NOTES:

NONE

4.4.15. setpgid - Set Process Group ID for Job Control¶

CALLING SEQUENCE:

int setpgid(
    pid_t pid,
    pid_t pgid
);

STATUS CODES:

DESCRIPTION:

This service is not implemented for RTEMS as process groups are not supported.

NOTES:

NONE

4.4.16. uname - Get System Name¶

CALLING SEQUENCE:

int uname(
    struct utsname *name
);

STATUS CODES:

DESCRIPTION:

This service returns system information to the caller. It does this by filling in the struct utsname format structure for the caller.

NOTES:

The information provided includes the operating system (RTEMS in all configurations), the node number, the release as the RTEMS version, and the CPU family and model. The CPU model name will indicate the multilib executive variant being used.

4.4.17. times - Get process times¶

CALLING SEQUENCE:

#include <sys/time.h>
clock_t times(
    struct tms *ptms
);

STATUS CODES:

This routine returns the number of clock ticks that have elapsed since the system was initialized (e.g. the application was started).

DESCRIPTION:

times stores the current process times in ptms. The format of struct tms is as defined in <sys/times.h>. RTEMS fills in the field tms_utime with the number of ticks that the calling thread has executed and the field tms_stime with the number of clock ticks since system boot (also returned). All other fields in the ptms are left zero.

NOTES:

RTEMS has no way to distinguish between user and system time so this routine returns the most meaningful information possible.

4.4.18. getenv - Get Environment Variables¶

CALLING SEQUENCE:

char *getenv(
    const char *name
);

STATUS CODES:

DESCRIPTION:

This service searches the set of environment variables for a string that matches the specified name. If found, it returns the associated value.

NOTES:

The environment list consists of name value pairs that are of the form name = value.

4.4.19. setenv - Set Environment Variables¶

CALLING SEQUENCE:

int setenv(
    const char *name,
    const char *value,
    int overwrite
);

STATUS CODES:

Returns 0 if successful and -1 otherwise.

DESCRIPTION:

This service adds the variable name to the environment with value. If name is not already exist, then it is created. If name exists and overwrite is zero, then the previous value is not overwritten.

NOTES:

NONE

4.4.20. ctermid - Generate Terminal Pathname¶

CALLING SEQUENCE:

char *ctermid(
    char *s
);

STATUS CODES:

Returns a pointer to a string indicating the pathname for the controlling terminal.

DESCRIPTION:

This service returns the name of the terminal device associated with this process. If s is NULL, then a pointer to a static buffer is returned. Otherwise, s is assumed to have a buffer of sufficient size to contain the name of the controlling terminal.

NOTES:

By default on RTEMS systems, the controlling terminal is /dev/console. Again this implementation is of limited meaning, but it provides true and useful results which should be sufficient to ease porting applications from a full POSIX implementation to the reduced profile supported by RTEMS.

4.4.21. ttyname - Determine Terminal Device Name¶

CALLING SEQUENCE:

char *ttyname(
    int fd
);

STATUS CODES:

Pointer to a string containing the terminal device name or NULL is returned on any error.

DESCRIPTION:

This service returns a pointer to the pathname of the terminal device that is open on the file descriptor fd. If fd is not a valid descriptor for a terminal device, then NULL is returned.

NOTES:

This routine uses a static buffer.

4.4.22. ttyname_r - Reentrant Determine Terminal Device Name¶

CALLING SEQUENCE:

int ttyname_r(
    int   fd,
    char *name,
    int   namesize
);

STATUS CODES:

This routine returns -1 and sets errno as follows:

DESCRIPTION:

This service the pathname of the terminal device that is open on the file descriptor fd.

NOTES:

NONE

4.4.23. isatty - Determine if File Descriptor is Terminal¶

CALLING SEQUENCE:

int isatty(
    int fd
);

STATUS CODES:

Returns 1 if fd is a terminal device and 0 otherwise.

DESCRIPTION:

This service returns 1 if fd is an open file descriptor connected to a terminal and 0 otherwise.

NOTES:

4.4.24. sysconf - Get Configurable System Variables¶

CALLING SEQUENCE:

long sysconf(
    int name
);

STATUS CODES:

The value returned is the actual value of the system resource. If the requested configuration name is a feature flag, then 1 is returned if the available and 0 if it is not. On any other error condition, -1 is returned.

DESCRIPTION:

This service is the mechanism by which an application determines values for system limits or options at runtime.

NOTES:

Much of the information that may be obtained via sysconf has equivalent macros in unistd.h. However, those macros reflect conservative limits which may have been altered by application configuration.

5.2.1. Path Name Evaluation¶

A pathname is a string that consists of no more than PATH_MAX bytes, including the terminating null character. A pathname has an optional beginning slash, followed by zero or more filenames separated by slashes. If the pathname refers to a directory, it may also have one or more trailing slashes. Multiple successive slahes are considered to be the same as one slash.

POSIX allows a pathname that begins with precisely two successive slashes to be interpreted in an implementation-defined manner. RTEMS does not currently recognize this as a special condition. Any number of successive slashes is treated the same as a single slash. POSIX requires that an implementation treat more than two leading slashes as a single slash.

5.4.1. opendir - Open a Directory¶

CALLING SEQUENCE:

#include <sys/types.h>
#include <dirent.h>
int opendir(
    const char *dirname
);

STATUS CODES:

DESCRIPTION:

This routine opens a directory stream corresponding to the directory specified by the dirname argument. The directory stream is positioned at the first entry.

NOTES:

The routine is implemented in Cygnus newlib.

5.4.2. readdir - Reads a directory¶

CALLING SEQUENCE:

#include <sys/types.h>
#include <dirent.h>
    int readdir(
    DIR *dirp
);

STATUS CODES:

DESCRIPTION:

The readdir() function returns a pointer to a structure dirent representing the next directory entry from the directory stream pointed to by dirp. On end-of-file, NULL is returned.

The readdir() function may (or may not) return entries for . or .. Your program should tolerate reading dot and dot-dot but not require them.

The data pointed to be readdir() may be overwritten by another call to readdir() for the same directory stream. It will not be overwritten by a call for another directory.

NOTES:

If ptr is not a pointer returned by malloc(), calloc(), or realloc() or has been deallocated with free() or realloc(), the results are not portable and are probably disastrous.

The routine is implemented in Cygnus newlib.

5.4.3. rewinddir - Resets the readdir() pointer¶

CALLING SEQUENCE:

#include <sys/types.h>
#include <dirent.h>
void rewinddir(
    DIR *dirp
);

STATUS CODES:

No value is returned.

DESCRIPTION:

The rewinddir() function resets the position associated with the directory stream pointed to by dirp. It also causes the directory stream to refer to the current state of the directory.

NOTES:

NONE

If dirp is not a pointer by opendir(), the results are undefined.

The routine is implemented in Cygnus newlib.

5.4.4. scandir - Scan a directory for matching entries¶

CALLING SEQUENCE:

#include <dirent.h>
int scandir(
    const char       *dir,
    struct dirent ***namelist,
    int  (*select)(const struct dirent *),
    int  (*compar)(const struct dirent **, const struct dirent **)
);

STATUS CODES:

DESCRIPTION:

The scandir() function scans the directory dir, calling select() on each directory entry. Entries for which select() returns non-zero are stored in strings allocated via malloc(), sorted using qsort() with the comparison function compar(), and collected in array namelist which is allocated via malloc(). If select is NULL, all entries are selected.

NOTES:

The routine is implemented in Cygnus newlib.

5.4.5. telldir - Return current location in directory stream¶

CALLING SEQUENCE:

#include <dirent.h>
off_t telldir(
    DIR *dir
);

STATUS CODES:

DESCRIPTION:

The telldir() function returns the current location associated with the directory stream dir.

NOTES:

The routine is implemented in Cygnus newlib.

5.4.6. closedir - Ends directory read operation¶

CALLING SEQUENCE:

#include <sys/types.h>
#include <dirent.h>
int closedir(
    DIR *dirp
);

STATUS CODES:

DESCRIPTION:

The directory stream associated with dirp is closed. The value in dirp may not be usable after a call to closedir().

NOTES:

NONE

The argument to closedir() must be a pointer returned by opendir(). If it is not, the results are not portable and most likely unpleasant.

The routine is implemented in Cygnus newlib.

5.4.7. chdir - Changes the current working directory¶

CALLING SEQUENCE:

#include <unistd.h>
int chdir(
    const char *path
);

STATUS CODES:

On error, this routine returns -1 and sets errno to one of the following:

DESCRIPTION:

The chdir() function causes the directory named by path to become the current working directory; that is, the starting point for searches of pathnames not beginning with a slash.

If chdir() detects an error, the current working directory is not changed.

NOTES:

NONE

5.4.8. fchdir - Changes the current working directory¶

CALLING SEQUENCE:

#include <unistd.h>
int fchdir(
    int fd
);

STATUS CODES:

On error, this routine returns -1 and sets errno to one of the following:

DESCRIPTION:

The fchdir() function causes the directory named by fd to become the current working directory; that is, the starting point for searches of pathnames not beginning with a slash.

If fchdir() detects an error, the current working directory is not changed.

NOTES:

NONE

5.4.9. getcwd - Gets current working directory¶

CALLING SEQUENCE:

#include <unistd.h>
int getcwd( void );

STATUS CODES:

DESCRIPTION:

The getcwd() function copies the absolute pathname of the current working directory to the character array pointed to by buf. The size argument is the number of bytes available in buf

NOTES:

There is no way to determine the maximum string length that fetcwd() may need to return. Applications should tolerate getting ERANGE and allocate a larger buffer.

It is possible for getcwd() to return EACCES if, say, login puts the process into a directory without read access.

The 1988 standard uses int instead of size_t for the second parameter.

5.4.10. open - Opens a file¶

CALLING SEQUENCE:

#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
int open(
    const char *path,
    int         oflag,
    mode_t      mode
);

STATUS CODES:

DESCRIPTION:

The open function establishes a connection between a file and a file descriptor. The file descriptor is a small integer that is used by I/O functions to reference the file. The path argument points to the pathname for the file.

The oflag argument is the bitwise inclusive OR of the values of symbolic constants. The programmer must specify exactly one of the following three symbols:

Any combination of the following symbols may also be used.

Upon successful completion, open returns a non-negative file descriptor.

NOTES:

NONE

5.4.11. creat - Create a new file or rewrite an existing one¶

CALLING SEQUENCE:

#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
int creat(
    const char *path,
    mode_t      mode
);

STATUS CODES:

DESCRIPTION:

creat attempts to create a file and return a file descriptor for use in read, write, etc.

NOTES:

NONE

The routine is implemented in Cygnus newlib.

5.4.12. umask - Sets a file creation mask.¶

CALLING SEQUENCE:

#include <sys/types.h>
#include <sys/stat.h>
mode_t umask(
    mode_t cmask
);

STATUS CODES:

DESCRIPTION:

The umask() function sets the process file creation mask to cmask. The file creation mask is used during open(), creat(), mkdir(), mkfifo() calls to turn off permission bits in the mode argument. Bit positions that are set in cmask are cleared in the mode of the created file.

NOTES:

NONE

The cmask argument should have only permission bits set. All other bits should be zero.

In a system which supports multiple processes, the file creation mask is inherited across fork() and exec() calls. This makes it possible to alter the default permission bits of created files. RTEMS does not support multiple processes so this behavior is not possible.

5.4.13. link - Creates a link to a file¶

CALLING SEQUENCE:

#include <unistd.h>
int link(
    const char *existing,
    const char *new
);

STATUS CODES:

DESCRIPTION:

The link() function atomically creates a new link for an existing file and increments the link count for the file.

If the link() function fails, no directories are modified.

The existing argument should not be a directory.

The caller may (or may not) need permission to access the existing file.

NOTES:

NONE

5.4.14. symlink - Creates a symbolic link to a file¶

CALLING SEQUENCE:

#include <unistd.h>
int symlink(
    const char *topath,
    const char *frompath
);

STATUS CODES:

DESCRIPTION:

The symlink() function creates a symbolic link from the frombath to the topath. The symbolic link will be interpreted at run-time.

If the symlink() function fails, no directories are modified.

The caller may (or may not) need permission to access the existing file.

NOTES:

NONE

5.4.15. readlink - Obtain the name of a symbolic link destination¶

CALLING SEQUENCE:

#include <unistd.h>
int readlink(
    const char *path,
    char       *buf,
    size_t      bufsize
);

STATUS CODES:

DESCRIPTION:

The readlink() function places the symbolic link destination into buf argument and returns the number of characters copied.

If the symbolic link destination is longer than bufsize characters the name will be truncated.

NOTES:

NONE

5.4.16. mkdir - Makes a directory¶

CALLING SEQUENCE:

#include <sys/types.h>
#include <sys/stat.h>
int mkdir(
    const char *path,
    mode_t      mode
);

STATUS CODES:

DESCRIPTION:

The mkdir() function creates a new diectory named path. The permission bits (modified by the file creation mask) are set from mode. The owner and group IDs for the directory are set from the effective user ID and group ID.

The new directory may (or may not) contain entries for . and .. but is otherwise empty.

NOTES:

NONE

5.4.17. mkfifo - Makes a FIFO special file¶

CALLING SEQUENCE:

#include <sys/types.h>
#include <sys/stat.h>
int mkfifo(
    const char *path,
    mode_t      mode
);

STATUS CODES:

DESCRIPTION:

The mkfifo() function creates a new FIFO special file named path. The permission bits (modified by the file creation mask) are set from mode. The owner and group IDs for the FIFO are set from the efective user ID and group ID.

NOTES:

NONE

5.4.18. unlink - Removes a directory entry¶

CALLING SEQUENCE:

#include <unistd.h>
int unlink(
    const char path
);

STATUS CODES:

DESCRIPTION:

The unlink function removes the link named by path and decrements the link count of the file referenced by the link. When the link count goes to zero and no process has the file open, the space occupied by the file is freed and the file is no longer accessible.

NOTES:

NONE

5.4.19. rmdir - Delete a directory¶

CALLING SEQUENCE:

#include <unistd.h>
int rmdir(
    const char *pathname
);

STATUS CODES:

DESCRIPTION:

rmdir deletes a directory, which must be empty

NOTES:

NONE

5.4.20. rename - Renames a file¶

CALLING SEQUENCE:

#include <unistd.h>
int rename(
    const char *old,
    const char *new
);

STATUS CODES:

DESCRIPTION:

The rename() function causes the file known bo old to now be known as new.

Ordinary files may be renamed to ordinary files, and directories may be renamed to directories; however, files cannot be converted using rename(). The new pathname may not contain a path prefix of old.

NOTES:

If a file already exists by the name new, it is removed. The rename() function is atomic. If the rename() detects an error, no files are removed. This guarantees that the rename("x", "x") does not remove x.

You may not rename dot or dot-dot.

The routine is implemented in Cygnus newlib using link() and unlink().

5.4.21. stat - Gets information about a file¶

CALLING SEQUENCE:

#include <sys/types.h>
#include <sys/stat.h>
int stat(
    const char  *path,
    struct stat *buf
);

STATUS CODES:

DESCRIPTION:

The path argument points to a pathname for a file. Read, write, or execute permission for the file is not required, but all directories listed in path must be searchable. The stat() function obtains information about the named file and writes it to the area pointed to by buf.

NOTES:

NONE

5.4.22. fstat - Gets file status¶

CALLING SEQUENCE:

#include <sys/types.h>
#include <sys/stat.h>
int fstat(
    int          fildes,
    struct stat *buf
);

STATUS CODES:

DESCRIPTION:

The fstat() function obtains information about the file associated with fildes and writes it to the area pointed to by the buf argument.

NOTES:

If the filesystem object referred to by fildes is a link, then the information returned in buf refers to the destination of that link. This is in contrast to lstat() which does not follow the link.

5.4.23. lstat - Gets file status¶

CALLING SEQUENCE:

#include <sys/types.h>
#include <sys/stat.h>
int lstat(
    int          fildes,
    struct stat *buf
);

STATUS CODES:

DESCRIPTION:

The lstat() function obtains information about the file associated with fildes and writes it to the area pointed to by the buf argument.

NOTES:

If the filesystem object referred to by fildes is a link, then the information returned in buf refers to the link itself. This is in contrast to fstat() which follows the link.

The lstat() routine is defined by BSD 4.3 and SVR4 and not included in POSIX 1003.1b-1996.

5.4.24. access - Check permissions for a file¶

CALLING SEQUENCE:

#include <unistd.h>
int access(
    const char *pathname,
    int         mode
);

STATUS CODES:

DESCRIPTION:

Access checks whether the process would be allowed to read, write or test for existence of the file (or other file system object) whose name is pathname. If pathname is a symbolic link permissions of the file referred by this symbolic link are tested.

Mode is a mask consisting of one or more of R_OK, W_OK, X_OK and F_OK.

NOTES:

NONE

5.4.25. chmod - Changes file mode.¶

CALLING SEQUENCE:

#include <sys/types.h>
#include <sys/stat.h>
int chmod(
    const char *path,
    mode_t      mode
);

STATUS CODES:

DESCRIPTION:

Set the file permission bits, the set user ID bit, and the set group ID bit for the file named by path to mode. If the effective user ID does not match the owner of the file and the calling process does not have the appropriate privileges, chmod() returns -1 and sets errno to EPERM.

NOTES:

NONE

5.4.26. fchmod - Changes permissions of a file¶

CALLING SEQUENCE:

#include <sys/types.h>
#include <sys/stat.h>
int fchmod(
    int    fildes,
    mode_t mode
);

STATUS CODES:

DESCRIPTION:

The mode of the file given by path or referenced by filedes is changed.

NOTES:

NONE

5.4.27. getdents - Get directory entries¶

CALLING SEQUENCE:

#include <unistd.h>
#include <linux/dirent.h>
#include <linux/unistd.h>
long getdents(
    int   dd_fd,
    char *dd_buf,
    int   dd_len
);

STATUS CODES:

A successful call to getdents returns th the number of bytes read. On end of directory, 0 is returned. When an error occurs, -1 is returned, and errno is set appropriately.

DESCRIPTION:

getdents reads several dirent structures from the directory pointed by fd into the memory area pointed to by dirp. The parameter count is the size of the memory area.

NOTES:

NONE

5.4.28. chown - Changes the owner and/or group of a file.¶

CALLING SEQUENCE:

#include <sys/types.h>
#include <unistd.h>
int chown(
    const char *path,
    uid_t       owner,
    gid_t       group
);

STATUS CODES:

DESCRIPTION:

The user ID and group ID of the file named by path are set to owner and path, respectively.

For regular files, the set group ID (S_ISGID) and set user ID (S_ISUID) bits are cleared.

Some systems consider it a security violation to allow the owner of a file to be changed, If users are billed for disk space usage, loaning a file to another user could result in incorrect billing. The chown() function may be restricted to privileged users for some or all files. The group ID can still be changed to one of the supplementary group IDs.

NOTES:

This function may be restricted for some file. The pathconf function can be used to test the _PC_CHOWN_RESTRICTED flag.

5.4.29. utime - Change access and/or modification times of an inode¶

CALLING SEQUENCE:

#include <sys/types.h>
int utime(
    const char     *filename,
    struct utimbuf *buf
);

STATUS CODES:

DESCRIPTION:

Utime changes the access and modification times of the inode specified by filename to the actime and modtime fields of buf respectively. If buf is NULL, then the access and modification times of the file are set to the current time.

NOTES:

NONE

5.4.30. ftruncate - truncate a file to a specified length¶

CALLING SEQUENCE:

#include <unistd.h>
int ftrunctate(
    int    fd,
    size_t length
);

STATUS CODES:

DESCRIPTION:

truncate() causes the file named by path or referenced by fd to be truncated to at most length bytes in size. If the file previously was larger than this size, the extra data is lost. With ftruncate(), the file must be open for writing.

NOTES:

NONE

5.4.31. truncate - truncate a file to a specified length¶

CALLING SEQUENCE:

#include <unistd.h>
int trunctate(
    const char *path,
    size_t      length
);

STATUS CODES:

DESCRIPTION:

truncate() causes the file named by path or referenced by``fd`` to be truncated to at most length bytes in size. If the file previously was larger than this size, the extra data is lost. With ftruncate(), the file must be open for writing.

NOTES:

NONE

5.4.32. pathconf - Gets configuration values for files¶

CALLING SEQUENCE:

#include <unistd.h>
int pathconf(
    const char *path,
    int         name
);

STATUS CODES:

DESCRIPTION:

pathconf() gets a value for the configuration option name for the open file descriptor filedes.

The possible values for name are:

NOTES:

Files with name lengths longer than the value returned for name equal _PC_NAME_MAX may exist in the given directory.

5.4.33. fpathconf - Gets configuration values for files¶

CALLING SEQUENCE:

#include <unistd.h>
int fpathconf(
    int filedes,
    int name
);

STATUS CODES:

DESCRIPTION:

pathconf() gets a value for the configuration option name for the open file descriptor filedes.

The possible values for name are:

NOTES:

NONE

5.4.34. mknod - create a directory¶

CALLING SEQUENCE:

#include <unistd.h>
#include <fcntl.h>
#include <sys/types.h>
#include <sys/stat.h>
long mknod(
    const char *pathname,
    mode_t      mode,
    dev_t       dev
);

STATUS CODES:

mknod returns zero on success, or -1 if an error occurred (in which case, errno is set appropriately).

DESCRIPTION:

mknod attempts to create a filesystem node (file, device special file or named pipe) named pathname, specified by mode and dev.

mode specifies both the permissions to use and the type of node to be created.

It should be a combination (using bitwise OR) of one of the file types listed below and the permissions for the new node.

The permissions are modified by the process’s umask in the usual way: the permissions of the created node are (mode & ~umask).

The file type should be one of S_IFREG, S_IFCHR, S_IFBLK and S_IFIFO to specify a normal file (which will be created empty), character special file, block special file or FIFO (named pipe), respectively, or zero, which will create a normal file.

If the file type is S_IFCHR or S_IFBLK then dev specifies the major and minor numbers of the newly created device special file; otherwise it is ignored.

The newly created node will be owned by the effective uid of the process. If the directory containing the node has the set group id bit set, or if the filesystem is mounted with BSD group semantics, the new node will inherit the group ownership from its parent directory; otherwise it will be owned by the effective gid of the process.

NOTES:

NONE

6.4.1. pipe - Create an Inter-Process Channel¶

CALLING SEQUENCE:

#include <unistd.h>
int pipe(
    int fildes[2]
);

STATUS CODES:

DESCRIPTION:

NOTES:

This routine is not currently supported by RTEMS but could be in a future version.

6.4.2. dup - Duplicates an open file descriptor¶

CALLING SEQUENCE:

#include <unistd.h>
int dup(
    int fildes
);

STATUS CODES:

DESCRIPTION:

The dup function returns the lowest numbered available file descriptor. This new desciptor refers to the same open file as the original descriptor and shares any locks.

NOTES:

NONE

6.4.3. dup2 - Duplicates an open file descriptor¶

CALLING SEQUENCE:

#include <unistd.h>
int dup2(
    int fildes,
    int fildes2
);

STATUS CODES:

DESCRIPTION:

dup2 creates a copy of the file descriptor oldfd.

The old and new descriptors may be used interchangeably. They share locks, file position pointers and flags; for example, if the file position is modified by using lseek on one of the descriptors, the position is also changed for the other.

NOTES:

NONE

6.4.4. close - Closes a file¶

CALLING SEQUENCE:

#include <unistd.h>
int close(
    int fildes
);

STATUS CODES:

DESCRIPTION:

The close() function deallocates the file descriptor named by fildes and makes it available for reuse. All outstanding record locks owned by this process for the file are unlocked.

NOTES:

A signal can interrupt the close() function. In that case, close() returns -1 with errno set to EINTR. The file may or may not be closed.

6.4.5. read - Reads from a file¶

CALLING SEQUENCE:

#include <unistd.h>
ssize_t read(
    int fildes,
    void *buf,
    size_t nbyte
);

STATUS CODES:

On error, this routine returns -1 and sets errno to one of the following:

DESCRIPTION:

The read() function reads nbyte bytes from the file associated with fildes into the buffer pointed to by buf.

The read() function returns the number of bytes actually read and placed in the buffer. This will be less than nbyte if:

• The number of bytes left in the file is less than nbyte.

• The read() request was interrupted by a signal.

• The file is a pipe or FIFO or special file with less than nbytes immediately available for reading.

When attempting to read from any empty pipe or FIFO:

• If no process has the pipe open for writing, zero is returned to indicate end-of-file.

• If some process has the pipe open for writing and O_NONBLOCK is set, -1 is returned and errno is set to EAGAIN.

• If some process has the pipe open for writing and O_NONBLOCK is clear, read() waits for some data to be written or the pipe to be closed.

When attempting to read from a file other than a pipe or FIFO and no data is available.

• If O_NONBLOCK is set, -1 is returned and errno is set to EAGAIN.

• If O_NONBLOCK is clear, read() waits for some data to become available.

• The O_NONBLOCK flag is ignored if data is available.

NOTES:

NONE

6.4.6. write - Writes to a file¶

CALLING SEQUENCE:

#include <unistd.h>
ssize_t write(
    int fildes,
    const void *buf,
    size_t nbyte
);

STATUS CODES:

DESCRIPTION:

The write() function writes nbyte from the array pointed to by buf into the file associated with fildes.

If nybte is zero and the file is a regular file, the write() function returns zero and has no other effect. If nbyte is zero and the file is a special file, te results are not portable.

The write() function returns the number of bytes written. This number will be less than nbytes if there is an error. It will never be greater than nbytes.

NOTES:

NONE

6.4.7. fcntl - Manipulates an open file descriptor¶

CALLING SEQUENCE:

#include <fcntl.h>
int fcntl(
    int fildes,
    int cmd,
    ...
);

STATUS CODES:

DESCRIPTION:

fcntl() performs one of various miscellaneous operations on``fd``. The operation in question is determined by cmd: