| Previous | Contents | Index |
Sets the process group ID for job control.
#include <unistd.h>int setpgid (pid_t pid, pid_t pgid);
pid
The process ID for which the process group ID is to be set.pgid
The value to which the process group ID is set.
The setpgid function is used either to join an existing process group or create a new process group within the session of the calling process. The process group ID of a session leader will not change.Upon successful completion, the process group ID of the process with a process ID of pid is set to pgid. As a special case, if pid is 0, the process ID of the calling process is used. Also, if pgid is 0, the process group ID of the indicated process is used.
This function requires that long (32-bit) UID/GID support be enabled. See Section 1.5.8 for more information.
0 Successful completion. - 1 Indicates an error. The function sets errno to one of the following values:
- EACCES -- The value of the pid argument matches the process ID of a child process of the calling process and the child process has successfully executed one of the exec functions.
- EINVAL -- The value of the pgid argument is less than 0, or is not a value supported by the implementation.
- EPERM -- The process indicated by the pid argument is a session leader. The value of the pid argument matches the process ID of a child process of the calling process, and the child process is not in the same session as the calling process. The value of the pgid argument is valid but does not match the process ID of the process indicated by the pid argument, and there is no process with a process group ID that matches the value of the pgid argument in the same session as the calling process.
- ESRCH -- The value of the pid argument does not match the process ID of the calling process or of a child process of the calling process.
Sets the process group ID.
#include <unistd.h>pid_t setpgrp (void);
If the calling process is not already a session leader, setpgrp sets the process group ID of the calling process to the process ID of the calling process. If setpgrp creates a new session, then the new session has no controlling terminal.The setpgrp function has no effect when the calling process is a session leader.
This function requires that long (32-bit) UID/GID support be enabled. See Section 1.5.8 for more information.
x The process group ID of the calling process.
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.
This function requires that long (32-bit) UID/GID support be enabled. See Section 1.5.8 for more information.
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.
This function requires that long (32-bit) UID/GID support be enabled. See Section 1.5.8 for more information.
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.This function requires that long (32-bit) UID/GID support be enabled. See Section 1.5.8 for more information.
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> : _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 C RTL provides the following types of ANSI-conforming file buffering:
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 _IOLBF and _IOFBF defined in <stdio.h> for the type argument to specify line-buffered and fully buffered I/O, respectively.
If file_ptr specifies a terminal device, the HP C RTL uses line-buffered I/O; otherwise, it uses fully buffered I/O.
Please note that the previously documented value _IONBF is not supported.
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).
Opens a shared memory object.
#include <sys/mman.h>int shm_open (const char *name, int oflag, mode_t mode);
name
Pointer to a string naming a shared memory object.oflag
Specifies options that define file status and file access modes. This argument is constructed from the bitwise inclusive OR of zero or more of the options defined in the <fcntl.h> header file.mode
The shared memory object's permission bits. This argument is used only when the shared memory object is being created.
The shm_open function establishes a connection between a shared memory object and a file descriptor. It creates an open file description that refers to the shared memory object and a file descriptor that refers to that open file description. The file descriptor is used by other functions to refer to that shared memory object. The name argument points to a string naming a shared memory object. The name can be a pathname, in which case other processes referring to the same pathname refer to the same shared memory object.When a shared memory object is created, its state and all data associated with it persist until the shared memory is unlinked.
The shm_open function returns a file descriptor for the shared memory object that is the lowest numbered file descriptor not currently open for that process.
The file status flags and file access modes of the open file description are set according to the value of oflag, and can have zero or more of the following values:
O_RDONLY -- Open for read access only.
O_RDWR -- Open for read or write access.
O_CREAT -- Create the shared memory if the memory object does not exist already. The user ID and group ID of the shared memory object are identical to those of the calling process. The shared memory object's permission bits are set to the value of mode, except those set in the file mode creation mask of the process.
O_EXCL -- Prevent the opening of a shared memory object if O_CREAT is set and the shared memory object already exists. Use this option only in combination with O_CREAT.
O_TRUNC -- Truncate the shared memory object to zero length if it is successfully opened for read or write access (O_RDWR).The initial contents of the shared memory object are binary zeros.
n Upon success, a nonnegative integer representing the lowest numbered unused file descriptor. The file descriptor points to the shared memory object. - 1 Indicates failure. errno is set to indicate the error:
- EACCES -- Permission to create the shared memory object is denied, or the shared memory object exists and the permissions specified by oflag are denied, or O_TRUNC is specified and write permission is denied.
- EEXIST -- O_CREAT and O_EXCL are set, but the named shared memory object already exists.
- EINTR -- A signal has interrupted the shm_open operation.
- EINVAL -- The shm_open operation is not supported for the given name.
- EMFILE -- Too many file descriptors are currently in use by this process.
- ENAMETOOLONG -- The length of the name argument exceeds PATH_MAX or a pathname component is longer than NAME_MAX.
- ENFILE -- Too many shared memory objects are currently open in the system.
- ENOENT -- O_CREAT is not set and the named shared memory object does not exist.
- ENOSPC -- Memory space for creation of the new shared memory object is insufficient.
Removes a shared memory object.
#include <sys/mman.h>int shm_unlink (const char *name);
name
Pointer to a string naming the shared memory object to remove.
The shm_unlink function removes the name of the shared memory object named by the string pointed to by name.If one or more references to the shared memory object exist when the object is unlinked, the name is removed before shm_unlink returns, but the removal of the memory object contents is postponed until all open and map references to the shared memory object have been removed.
Even if the object continues to exist after the last shm_unlink , reuse of the name subsequently causes shm_unlink to behave as if no shared memory object with this name exists (that is, shm_open will fail if O_CREAT is not set, or will create a new shared memory object if O_CREAT is set).
0 Indicates success. - 1 Indicates failure, the named shared memory object is not changed by the function call, and errno is set to indicate the error:
- EACCES -- Permission is denied to unlink the named shared memory object.
- ENAMETOOLONG -- The length of the name argument exceeds PATH_MAX or a pathname component is longer than NAME_MAX.
- ENOENT -- The named shared memory object does not exist.
| Previous | Next | Contents | Index |