|
HP OpenVMS Systems Documentation |
|
HP C
|
| Previous | Contents | Index |
Rewinds the user database.
#include <pwd.h>void setpwent (void);
The setpwent function effectively rewinds the user database to allow repeated searches.No value is returned, but errno is set to EIO if an I/O error occurred.
See also getpwent .
Sets the real and effective group IDs.
#include <unistd.h>int setregid (gid_t rgid, gid_t egid);
rgid
The value to which you want the real group ID set.egid
The value to which you want the effective group ID set.
The setregid function is used to set the real and effective group IDs of the calling process. If rgid is - 1, the real group ID is not changed; if egid is - 1, the effective group ID is not changed. The real and effective group IDs can be set to different values in the same call.Only a process with the IMPERSONATE privilege can set the real group ID and the effective group ID to any valid value.
A nonprivileged process can set either the real group ID to the saved set-group-ID from an exec function, or the effective group ID to the saved set-group-ID or the real group ID.
Any supplementary group IDs of the calling process remain unchanged.
If a set-group-ID process sets its effective group ID to its real group ID, it can still set its effective group ID back to the saved set-group-ID.
0 Successful completion. - 1 Indicates an error. Neither of the group IDs is changed, and errno is set to one of the following values:
- EINVAL -- The value of the rgid or egid argument is invalid or out-of-range.
- EPERM -- The process does not have the IMPERSONATE privilege, and a change other than changing the real group ID to the saved set-group-ID, or changing the effective group ID to the real group ID or the saved group ID, was requested.
Sets the user IDs.
#include <unistd.h>int setreuid (uid_t ruid, uid_t euid);
ruid
The value to which you want the real user ID set.euid
The value to which you want the effective user ID set.
The setreuid function sets the real and effective user IDs of the current process to the values specified by the ruid and euid arguments. If ruid or euid is - 1, the corresponding effective or real user ID of the current process is left unchanged.A process with the IMPERSONATE privilege can set either ID to any value. An unprivileged process can set the effective user ID only if the euid argument is equal to either the real, effective, or saved user ID of the process.
It is unspecified whether a process without the IMPERSONATE privilege is permitted to change the real user ID to match the current real, effective, or saved user ID of the process.
0 Successful completion. - 1 Indicates an error. The function sets errno to one of the following values:
- EINVAL -- The value of the ruid or euid argument is invalid or out of range.
- EPERM -- The current process does not have the IMPERSONATE privilege, and either an attempt was made to change the effective user ID to a value other than the real user ID or the saved set-user-ID, or an an attempt was made to change the real user ID to a value not permitted by the implementation.
Creates a session and sets the process group ID.
#include <unistd.h>pid_t setsid (void);
The setsid function creates a new session if the calling process is not a process group leader. Upon return, the calling process is the session leader of this new session and the process group leader of a new process group, and it has no controlling terminal. The process group ID of the calling process is set equal to the process ID of the calling process. The calling process is the only process in the new process group and the only process in the new session.
x The process group ID of the calling process. (pid_t) - 1 Indicates an error. The function sets errno to the following value:
- EPERM -- The calling process is already a process group leader, or the process group ID of a process other than the calling process matches the process ID of the calling process.
Restarts and changes random-number generators.
char *setstate (char *state;)
state
Points to the array of state information.
The setstate function handles restarting and changing random-number generators.Once you initialize a state, the setstate function allows rapid switching between state arrays. The array defined by state is used for further random-number generation until the initstate function is called or the setstate function is called again. The setstate function returns a pointer to the previous state array.
After initialization, you can restart a state array at a different point in one of two ways:
- Use the initstate function, with the desired seed, state array, and size of the array.
- Use the setstate function, with the desired state, followed by the srandom function with the desired seed . The advantage of using both functions is that you do not have to save the state array size once you initialize it.
See also initstate , srandom , and random .
x A pointer to the previous state array information. 0 Indicates an error. The state information is damaged, and errno is set to the following value:
- EINVAL---The state argument is invalid.
With POSIX IDs disabled, implemented for program portability and serves no function. It returns 0 (to indicate success).With POSIX IDs enabled, sets the user IDs.
#include <types.h>#include <unistd.h>
int setuid (__uid_t uid); (_DECC_V4_SOURCE)
uid_t setuid (uid_t uid); (NOT _DECC_V4_SOURCE)
uid
The value to which you want the user IDs set.
The setuid function can be used with POSIX style identifiers enabled or disabled.POSIX style IDs are supported on OpenVMS Version 7.3-2 and higher.
With POSIX IDs disabled (the default), the setuid function is implemented for program portability and serves no function. It returns 0 (to indicate success).
With POSIX style IDs enabled:
- If the process has the IMPERSONATE privilege, the setuid function sets the real user ID, effective user ID, and the saved set-user-ID to uid.
- If the process does not have appropriate privileges but uid is equal to the real user ID or to the saved set-user-ID, then the setuid function sets the effective user ID to uid. The real user ID and saved set-user-ID remain unchanged.
To enable/disable POSIX style IDs, see Section 1.7.
0 Successful completion. - 1 Indicates an error. The function sets errno to one of the following values:
- EINVAL -- The value of the uid argument is invalid and not supported by the implementation.
- EPERM -- The process does not have appropriate privileges and uid does not match the real user ID or the saved set-user-ID.
Associates a buffer with an input or output file and potentially modifies the buffering behavior.
#include <stdio.h>int setvbuf (FILE *file_ptr, char *buffer, int type, size_t size);
file_ptr
A pointer to a file.buffer
A pointer to a character array, or a NULL pointer.type
The buffering type. Use one of the following values defined in <stdio.h> : _IONBF, _IOFBF, or _IOLBF.size
The number of bytes to be used in buffer by the HP C RTL for buffering this file. The buffer size must be a minimum of 8192 bytes and a maximum of 32767 bytes.
You can use the setvbuf function after the file is opened but before any I/O operations are performed.The ANSI C standard defines the following types of file buffering. In unbuffered I/O, each I/O operation is performed immediately. Output characters or lines are written to the output device before control is returned to the program. Input characters or lines are sent directly to the program without read-ahead by the HP C RTL.
In line-buffered I/O, characters are buffered in an area of memory until a new-line character is seen, at which point the appropriate RMS routine is called to transmit the entire buffer. Line buffering is more efficient than unbuffered I/O since it reduces the system overhead, but it delays the availability of the data to the user or disk on output.
In fully buffered I/O, characters are buffered in an area of memory until the buffer is full, regardless of the presence of break characters. Full buffering is more efficient than line buffering or unbuffered I/O, but it delays the availability of output data even longer than line buffering.
Use the values _IONBF, _IOLBF, and _IOFBF defined in <stdio.h> for the type argument to specify unbuffered, line-buffered, and fully buffered I/O, respectively.
If _IONBF is specified for type, I/O will be unbuffered and the buffer and size arguments are ignored.
If _IOLBF or _IOFBF is specified for type, the HP C RTL will use line-buffered I/O if file_ptr specifies a terminal device; otherwise, it will use fully buffered I/O.
The HP C RTL automatically allocates a buffer to use for each I/O stream, so there are several buffer allocation possibilities:
- If buffer is not a NULL pointer and size is not smaller than the automatically allocated buffer, then setvbuf uses buffer as the file buffer.
- If buffer is a NULL pointer or size is smaller than the automatically allocated buffer, the automatically allocated buffer is used as the buffer area.
- If buffer is a NULL pointer and size is larger than the automatically allocated buffer, then setvbuf allocates a new buffer equal to the specified size and uses that as the file buffer.
User programs must not depend on the contents of buffer once I/O has been performed on the stream. The HP C RTL might or might not use buffer for any given I/O operation.
Generally, it is unnecessary to use setvbuf or setbuf to control the buffer size used by the HP C RTL. The automatically allocated buffer sizes are chosen for efficiency based on the kind of I/O operations performed and the device characteristics (such as terminal, disk, or socket).
The setvbuf and setbuf functions are useful to introduce buffering for improved performance when writing a large amount of text to the stdout stream. This stream is unbuffered by default when bound to a terminal device (the normal case), and therefore incurs a large number of OpenVMS buffered I/O operations unless HP C RTL buffering is introduced by a call to setvbuf or setbuf .
The setvbuf function is used only to control the buffering used by the HP C RTL, not the buffering used by the underlying RMS I/O operations. You can modify RMS default buffering behavior by specifying various values for the ctx, fop, rat, gbc, mbc, mbf, rfm, and rop RMS keywords when the file is opened by the creat , freopen or open functions.
0 Indicates success. nonzero value Indicates that an invalid input value was specifed for type or file_ptr, or because file_ptr is being used by another thread (see Section 1.9.1).
Specifies the action to take upon delivery of a signal.
#include <signal.h>int sigaction (int sig, const struct sigaction *action, struct sigaction *o_action);
sig
The signal for which the action is to be taken.action
A pointer to a sigaction structure that describes the action to take when you receive the signal specified by the sig argument.o_action
A pointer to a sigaction structure. When the sigaction function returns from a call, the action previously attached to the specified signal is stored in this structure.
When a process requests the sigaction function, the process can both examine and specify what action to perform when the specified signal is delivered. The arguments determine the behavior of the sigaction function as follows:
- Specifying the sig argument identifies the affected signal. Use any one of the signal values defined in the <signal.h> header file, except SIGKILL.
If sig is SIGCHLD and the SA_NOCLDSTOP flag is not set in sa_flags , then a SIGCHLD signal is generated for the calling process whenever any of its child processes stop. If sig is SIGCHLD and the SA_NOCLDSTOP flag is set in sa_flags , then SIGCHLD signal is not generated in this way.- Specifying the action argument, if not null, points to a sigaction structure that defines what action to perform when the signal is received. If the action argument is null, signal handling remains unchanged, so you can use the call to inquire about the current handling of the signal.
- Specifying the o_action argument, if not null, points to a sigaction structure that contains the action previously attached to the specified signal.
The sigaction structure consists of the following members:
void (*sa_handler)(int); sigset_t sa_mask; int sa_flags;The sigaction structure members are defined as follows:
sa_handler This member can contain the following values:
- SIG_DFL -- Specifies the default action taken when the signal is delivered.
- SIG_IGN -- Specifies that the signal has no effect on the receiving process.
- Function pointer -- Requests to catch the signal. The signal causes the function call.
sa_mask This member can request that individual signals, in addition to those in the process signal mask, are blocked from delivery while the signal handler function specified by the sa_handler member is executing. sa_flags This member can set the flags to enable further control over the actions taken when a signal is delivered. The sa_flags member of the sigaction structure has the following values:
SA_ONSTACK Setting this bit causes the system to run the signal catching function on the signal stack specified by the sigstack function. If this bit is not set, the function runs on the stack of the process where the signal is delivered. SA_RESETHAND Setting this bit resets the signal to SIG_DFL. Be aware that you cannot automatically reset SIGILL and SIGTRAP. SA_NODEFER Setting this bit does not automatically block the signal as it is caught. SA_NOCLDSTOP If this bit is set and the sig argument is equal to SIGCHLD and a child process of the calling process stops, then a SIGCHLD signal is sent to the calling process only if SA_NOCLDSTOP is not set for SIGCHLD. When a signal is caught by a signal-catching function installed by sigaction , a new signal mask is calculated and installed for the duration of the signal-catching function (or until a call to either sigprocmask or sigsuspend is made. This mask is formed by taking the union of the current signal mask and the value of the sa_mask for the signal being delivered unless SA_NODEFER or SA_RESETHAND is set, and then including the signal being delivered. If and when the user's signal handler returns normally, the original signal mask is restored.
Once an action is installed for a specific signal, it remains installed until another action is explicitly requested (by another call to sigaction ), until the SA_RESETHAND flag causes resetting of the handler, or until one of the exec functions is called.
If the previous action for a specified signal had been established by signal , the values of the fields returned in the structure pointed to by the o_action argument of sigaction are unspecified, and in particular o_action-> sa_handler is not necessarily the same value passed to signal . However, if a pointer to the same structure or a copy thereof is passed to a subsequent call to sigaction by means of the action argument of sigaction ), the signal is handled as if the original call to signal were repeated.
If sigaction fails, no new signal handler is installed.
It is unspecified whether an attempt to set the action for a signal that cannot be caught or ignored to SIG_DFL is ignored or causes an error to be returned with errno set to EINVAL.
See Section 4.2 for more information on signal handling.
Note
The sigvec and signal functions are provided for compatibility to old UNIX systems; their function is a subset of that available with the sigaction function.See also sigstack , sigvec , signal , wait , read , and write .
0 Indicates success. - 1 Indicates an error; A new signal handler is not installed. errno is set to one of the following values:
- EFAULT -- The action or o_action argument points to a location outside of the allocated address space of the process.
- EINVAL -- The sig argument is not a valid signal number. Or an attempt was made to ignore or supply a handler for the SIGKILL, SIGSTOP, and SIGCONT signals.
| Previous | Next | Contents | Index |