HP OpenVMS Systems Documentation

Performs formatted input from the standard input ( stdin ), interpreting it according to the format specification. See Chapter 2 for information on format specifiers.

Format

#include <stdio.h>

int scanf (const char *format_spec, ...);

Arguments

format_spec

Pointer to a string containing the format specification. The format specification consists of characters to be taken literally from the input or converted and placed in memory at the specified input sources. For a list of conversion characters, see Chapter 2.

...

Optional expressions that are pointers to objects whose resultant types correspond to conversion specifications given in the format specification.

If no conversion specifications are given, you can omit these input pointers. Otherwise, the function call must have at least as many input pointers as there are conversion specifications, and the conversion specifications must match the types of the input pointers.

Conversion specifications are matched to input sources in left-to-right order. Excess input pointers, if any, are ignored.

Return Values

x	The number of successfully matched and assigned input items.
EOF	Indicates that a read error occurred prior to any successful conversions. The function sets errno . For a list of errno values set by this function, see fscanf .

Perform a scanf on the window. The scanw function acts on the stdscr window.

Format

#include <curses.h>

int scanw (char *format_spec, ...);

int wscanw (WINDOW *win, char *format_spec, ...);

Arguments

win

A pointer to the window.

format_spec

A pointer to the format specification string.

...

Optional expressions that are pointers to objects whose resultant types correspond to conversion specifications given in the format specification. If no conversion specifications are given, you may omit these input pointers.

Otherwise, the function call must have at least as many input pointers as there are conversion specifications, and the conversion specifications must match the types of the input pointers.

Conversion specifications are matched to input sources in left-to-right order. Excess input pointers, if any, are ignored.

Description

The formatting specification (format_spec) and the other arguments are identical to those used with the scanf function.

The scanw and wscanw functions accept, format, and return a line of text from the terminal screen. For more information, see the scrollok and scanf functions.

Return Values

OK	Indicates success.
ERR	Indicates that the function makes the screen scroll illegally or that the scan was unsuccessful.

Moves all the lines on the window up one line. The top line scrolls off the window and the bottom line becomes blank.

Format

#include <curses.h>

int scroll (WINDOW *win);

Argument

win

A pointer to the window.

Return Values

OK	Indicates success.
ERR	Indicates an error.

Sets the scroll flag for the specified window.

Format

#include <curses.h>

scrollok (WINDOW *win, bool boolf);

Arguments

win

A pointer to the window.

boolf

A Boolean TRUE or FALSE value. If boolf is FALSE, scrolling is not allowed. This is the default setting. The bool type is defined in the <curses.h> header file as follows:

#define bool int

Initializes a 48-bit random-number generator.

Format

#include <stdlib.h>

unsigned short *seed48 (unsigned short seed_16v[3]);

Argument

seed_16v

An array of three unsigned short int s that form a 48-bit seed value.

Description

The seed48 function initializes the random-number generator. You can use this function in your program before calling the drand48 , lrand48 , or mrand48 functions. (Although it is not recommended practice, constant default initializer values are supplied automatically if you call drand48 , lrand48 , or mrand48 without calling an initialization function).

The seed48 function works by generating a sequence of 48-bit integer values, Xi, according to the linear congruential formula:

Xn+1 = (aXn+c)mod m n > 0

The argument m equals 2⁴⁸ , so 48-bit integer arithmetic is performed. Unless you invoke the lcong48 function, the multiplier value a and the addend value c are:

a = 5DEECE66D16 = 2736731631558 c = B16 = 138

The initializer function seed48 :

• Sets the value of Xi to the 48-bit value specified in the array pointed to by seed_16v.
• Returns a pointer to a 48-bit internal buffer that contains the previous value of Xi, used only by seed48 .

The returned pointer allows you to restart the pseudorandom sequence at a given point. Use the pointer to copy the previous Xi value into a temporary array. To resume where the original sequence left off, you can call seed48 with a pointer to this array.

See also drand48 , lrand48 , and mrand48 .

Return Value

x	A pointer to a 48-bit internal buffer.

Sets the position of a directory stream.

Format

#include <dirent.h>

void seekdir (DIR *dir_pointer, long int location);

Arguments

dir_pointer

A pointer to the dir structure of an open directory.

location

The number of an entry relative to the start of the directory.

Description

The seekdir function sets the position of the next readdir operation on the directory stream specified by dir_pointer to the position specified by location. The value of location should be returned from an earlier call to telldir.

If the value of location was not returned by a call to the telldir function, or if there was an intervening call to the rewinddir function on this directory stream, the effect is unspecified.

The type DIR , defined in the <dirent.h> header file, represents a directory stream. A directory stream is an ordered sequence of all the directory entries in a particular directory. Directory entries represent files. You can remove files from or add files to a directory asynchronously to the operation of the readdir function.

See readdir , rewinddir , and telldir .

Deallocates the specified named semaphore.

Format

#include <semaphore.h>

int sem_close (sem_t *sem);

Argument

sem

The semaphore to be closed. Use the sem argument returned by the previous call to sem_open .

Description

The sem_close function makes a semaphore available for reuse by deallocating any system resources allocated for use by the current process for the named semaphore indicated by sem.

If the semaphore has not been removed with a call to sem_unlink , sem_close does not change the current state of the semaphore.

If the semaphore has been removed with a call to sem_unlink after the most recent call to sem_open with O_CREAT, the semaphore is no longer available after all processes that opened the semaphore close it.

Return Values

0	Successful completion.
- 1	Indicates an error. The function sets errno to one of the following values: EINVAL -- The sem argument is not a valid semaphore descriptor. ENOSYS -- The function is not implemented. EVMSERR -- OpenVMS specific nontranslatable error code.

Semaphore control operations.

Format

#include <sem.h>

int semctl (int semid, int semnum, int cmd, ...);

Argument

semid

A semaphore set identifier, a positive integer. It is created by the semget function and used to identify the semaphore set on which to perform the control operation.

semnum

Semaphore number, a non-negative integer. It identifies a semaphore within the semaphore set on which to perform the control operation.

cmd

The control operation to perform on the semaphore.

...

Optional fourth argument of type union semun , which depends on the control operation requested in cmd.

Description

The semctl function provides a variety of semaphore control operations as specified by cmd. The fourth argument is optional and depends upon the operation requested. If required, it is of type union semun , which is explicitly declared as:

union semun { int val; struct semid_ds *buf; unsigned short *array; } arg;

The following semaphore control operations as specified by cmd are executed with respect to the semaphore specified by semid and semnum. The level of permission required for each operation is shown with each command. The symbolic names for the values of cmd are defined in the <sem.h> header:

• GETVAL
  Returns the value of semval. Requires read permission.
• SETVAL
  Sets the value of semval to arg.val, where arg is the value of the fourth argument to semctl . When this command is successfully executed, the semadj value corresponding to the specified semaphore in all processes is cleared. Requires alter permission.
• GETPID
  Returns the value of sempid; requires read permission.

• GETNCNT
  Returns the value of semncnt; requires read permission.
• GETZCNT
  Returns the value of semzcnt; requires read permission.

The following values of cmd operate on each semval in the set of semaphores:

• GETALL
  Returns the value of semval for each semaphore in the semaphore set and places it into the array pointed to by arg.array, where arg is the fourth argument to semctl ; requires read permission.
• SETALL
  Sets the value of semval for each semaphore in the semaphore set according to the array pointed to by arg.array, where arg is the fourth argument to semctl . When this command is successfully executed, the semadj values corresponding to each specified semaphore in all processes are cleared. Requires alter permission.

The following values of cmd are also available:

• IPC_STAT
  Places the current value of each member of the semid_ds data structure associated with semid into the structure pointed to by arg.buf, where arg is the fourth argument to semctl . The contents of this structure are defined in <sem.h> . Requires read permission.
• IPC_SET
  Sets the value of the following members of the semid_ds data structure associated with semid to the corresponding value found in the structure pointed to by arg.buf, where arg is the fourth argument to semctl :

  sem_perm.uid sem_perm.gid sem_perm.mode

  
  The mode bits specified in The Open Group Base Specifications IPC General Description section are copied into the corresponding bits of the sem_perm.mode associated with semid. The stored values of any other bits are unspecified.
  This command can only be executed by a process that has an effective user ID equal to either that of a process with appropriate privileges or to the value of sem_perm.cuid or sem_perm.uid in the semid_ds data structure associated with semid.
• IPC_RMID
  Removes the semaphore identifier specified by semid from the system and destroys the set of semaphores and semid_ds data structure associated with it. This command can only be executed by a process that has an effective user ID equal to either that of a process with appropriate privileges or to the value of sem_perm.cuid or sem_perm.uid in the semid_ds data structure associated with semid.

Return Values

n or 0

Upon successful completion, the value returned by the function depends on cmd as follows: GETVAL - The value of semval GETPID - The value of sempid GETNCNT - The value of semncnt GETZCNT - The value of semzcnt All others - 0

- 1

Indicates an error. The function sets errno to one of the following values: EACCES -- Operation permission is denied to the calling process. EFAULT -- The arguments passed to the function are not accessible. EINVAL -- The value of semid is not a valid semaphore identifier, or the value of semnum is less than zero or greater than or equal to sem_nsems, or the value of cmd is not a valid command. EPERM -- The argument cmd is equal to IPC_RMID or IPC_SET and the effective user ID of the calling process is not equal to that of a process with appropriate privileges and it is not equal to the value of sem_perm.cuid or sem_perm.uid in the data structure associated with semid. EVMSERR -- OpenVMS specific nontranslatable error code.

Destroys an unnamed semaphore.

Format

#include <semaphore.h>

int sem_destroy (sem_t *sem);

Argument

sem

The unnamed semaphore to be destroyed. Use the sem argument that was supplied to, and filled in by, the previous call to sem_init .

Description

The sem_destroy function destroys an unnamed semaphore indicated by sem. Only a semaphore created using sem_init may be destroyed using sem_destroy .

The potential for deadlock exists if a process calls sem_destroy for a semaphore while there is a pending sem_wait , because a process may be waiting for a poster that has not yet opened the semaphore.

Return Values

0	Successful completion.
- 1	Indicates an error. The function sets errno to one of the following values, without destroying the semaphore indicated by the sem argument: EINVAL -- The sem argument is not a valid semaphore. ENOSYS -- The function is not implemented. EVMSERR -- OpenVMS specific nontranslatable error code. EBUSY -- The processes are blocked on the semaphore.

Gets a set of semaphores.

Format

#include <sem.h>

int semget (key_t key, int nsems, int semflg);

Argument

key

The key for which the associated semaphore identifier is returned.

nsems

Value used to initialize the sem_nsems member of the semid_ds data structure. See the description.

semflg

Flag used to initialize the low-order 9 bits of the sem_perm.mode member of the semid_ds data structure associated with the new semaphore. See the description.

value

The initial value to be given to the semaphore. This argument is used only when the semaphore is being created.

Description

The semget function returns the semaphore identifier associated with key.

A semaphore identifier with its associated semid_ds data structure and its associated set of nsems semaphores (see the <sys/sem.h> header file) is created for key if:

• The key argument does not already have a semaphore identifier associated with it and (semflg &IPC_CREAT) is nonzero.

When it is created, the semid_ds data structure associated with the new semaphore identifier is initialized as follows:

• In the operation permissions structure sem_perm.cuid, sem_perm.uid, sem_perm.cgid, and sem_perm.gid are set equal to the effective user ID and effective group ID, respectively, of the calling process.
• The low-order 9 bits of sem_perm.mode are set equal to the low-order 9 bits of the semflg argument.
• The variable sem_nsems is set equal to the value of the nsems argument.
• The variable sem_otime is set equal to 0 and the variable sem_ctime is set equal to the current time.
• The data structure associated with each semaphore in the set does not need to be initialized. You can use the semctl function with the command SETVAL or SETALL to initialize each semaphore.

Note The key argument value IPC_PRIVATE is not supported.

Return Values

n

Successful completion. The function returns a non-negative integer semaphore identifier.

- 1

Indicates an error. The function sets errno to one of the following values: EACCES -- A semaphore identifier exists for key, but operation permission as specified by the low-order 9 bits of semflg was not granted. EEXIST -- A semaphore identifier exists for key but ((semflg &IPC_CREAT) &&(semflg &IPC_EXCL)) is nonzero. EFAULT -- The arguments passed to the function are not accessible. EINVAL -- The value of nsems is either less than or equal to 0 or greater than the system-imposed limit, or a semaphore identifier exists for key, but the number of semaphores in the set associated with it is less than nsems and nsems is not equal to 0. ENOENT -- A semaphore identifier does not exist for key and ( semflg &IPC_CREAT) is equal to 0. ENOSPC -- A semaphore identifier is to be created but the system-imposed limit on the maximum number of allowed semaphores system-wide will be exceeded. EVMSERR -- OpenVMS specific nontranslatable error code.