Compaq C
User's Guide for OpenVMS Systems

The _FFS function finds the position of the first set bit in a field. The bits are tested for set status starting at bit 0 and extending to the highest bit in the field.

The _FFS function has the following format:

typedef enum { _ff_bit_not_found, _ff_bit_found} _FF_STATUS; _FF_STATUS _FFS (int __start, char __size, const void *__base, int *__position);

__start

The start position of the field.

__size

The size of the field, in bits. The size must be a value from 0 to 32 bits.

__base

The address of the field.

__position

The address of an integer to receive the position of the set bit. If no bit is set, the integer is set to the position of the first bit past the last bit tested.

There are two possible return values:

• _ff_bit_not_found (0) if all bits in the field are clear
• _ff_bit_found (1) if a bit with value 1 is found

The _HALT function halts the processor when executed by a process running in kernel mode. This is a privileged function.

The _HALT function has the following format:

void _HALT (void);

6.2.2.8 Insert Entry into Queue at Head Interlocked ( _INSQHI)

The _INSQHI function inserts an entry into the front of a queue in an indivisible manner. This operation is interlocked against similar operations by other processors or devices in the system.

The _INSQHI function has the following format:

typedef enum {_insqi_inserted_many, _insqi_not_inserted, _insqi_inserted_only} _INSQI_STATUS; _INSQI_STATUS _INSQHI (void *__new_entry, void *__head);

__new_entry

A pointer to the new entry to be inserted. The entry must be aligned on a quadword boundary. (You can achieve alignment using the _align or __align storage-class modifier.)

__head

A pointer to the queue header. The header must be aligned on a quadword boundary. (You can achieve alignment using the _align or __align storage-class modifier.)

There are three possible return values:

• _insqi_inserted_many (0) if the entry was inserted, but it was not the only entry in the list
• _insqi_not_inserted (1) if the entry was not inserted because the secondary interlock failed
• _insqi_inserted_only (2) if the entry was inserted and it was the only entry in the list

The _INSQTI function inserts an entry at the end of a queue in an indivisible manner. This operation is interlocked against similar operations by other processors or devices in the system.

The _INSQTI function has the following format:

typedef enum {_insqi_inserted_many, _insqi_not_inserted, _insqi_inserted_only} _INSQI_STATUS; _INSQI_STATUS _INSQTI (void *__new_entry, void *__head);

__new_entry

A pointer to the new entry to be inserted. The entry must be aligned on a quadword boundary. (You can achieve alignment using the _align or __align storage-class modifier.)

__head

A pointer to the queue header. The header must be aligned on a quadword boundary. (You can achieve alignment using the _align or __align storage-class modifier.)

There are three possible return values:

• _insqi_inserted_many (0) if the entry was inserted, but it was not the only entry in the list
• _insqi_not_inserted (1) if the entry was not inserted because the secondary interlock failed
• _insqi_inserted_only (2) if the entry was inserted and it was the only entry in the list

The _INSQUE function inserts a new entry into a queue following an existing entry.

The _INSQUE function has the following format:

typedef enum { _insque_inserted_only, _insque_inserted_many} _INSQUE_STATUS; _INSQUE_STATUS _INSQUE (void *__new_entry, void *__predecessor);

__new_entry

A pointer to the new entry to be inserted.

__predecessor

A pointer to an existing entry in the queue.

There are two possible return values:

• _insque_inserted_only (0) if the entry was the only entry in the queue
• _insque_inserted_many (1) if the entry was not the only entry in the queue

The _LOCC function locates the first character in a string matching the target character.

The _LOCC function has the following format:

unsigned short _LOCC (char __target, unsigned short __length, const char *__string, ...);

__target

The character being searched.

__length

The length of the searched string. The length must be a value from 0 to 65,535.

__string

A pointer to the searched string.

...

An optional position argument, which is a pointer to a pointer to char . If the searched character is found, this output argument is updated to point to the character found. If the character is not found, this argument is set to the address one byte beyond the string.

If the target character is found, the return value is the number of bytes remaining in the string; otherwise, the return value is 0.

6.2.2.12 Move from Processor Register ( _MFPR)

The _MFPR function returns the contents of a processor register. This is a privileged function.

The _MFPR function has the following formats:

void _MFPR (int register_num, int *destination); void _MFPR (int register_num, unsigned int *destination);

register_num

The number of the privileged register to be read.

destination

A pointer to the location receiving the value from the register. This location can be a signed or unsigned int .

The _MOVC3 function copies a block of memory.

The _MOVC3 function has the following format:

void _MOVC3 (unsigned short __length, const char *__src, char *__dest, ...);

__length

The length of the source string, in bytes. The length must be a value from 0 to 65,535.

__src

A pointer to the source string.

__dest

A pointer to the destination memory.

...

One or two optional arguments:

• endscr
  A pointer to a pointer to char . The _MOVC3 function sets this output argument to the address of the byte beyond the source string. Although this is an optional argument, it is required if enddest is specified.
• enddest
  A pointer to a pointer to char . The _MOVC3 function sets this output argument to the address of the byte beyond the destination string.

The _MOVC5 function allows the source string specified by the pointer and length pair to be moved to the destination string specified by the other pointer and length pair. If the source string is smaller than the destination string, the destination string is padded with the specified character.

The _MOVC5 function has the following format:

void _MOVC5 (unsigned short __srclen, const char *__src, char __fill, unsigned short __destlen, char *__dest, ...);

__srclen

The length of the source string, in bytes. The length must be a value from 0 to 65,535.

__src

A pointer to the source string.

__fill

The fill character to be used if the source string is smaller than the destination string.

__destlen

The length of the destination string, in bytes. The length must be a value from 0 to 65,535.

__dest

A pointer to the destination string.

...

One to three optional arguments:

• unmoved_src
  A pointer to an unsigned short integer. The _MOVC5 function sets this output argument to the number of unmoved bytes remaining in the source string. This argument is optional if the endscr argument is not specified.
• endscr
  A pointer to a pointer to char . The _MOVC5 function sets this output argument to the address of the byte beyond the source string. Although this is an optional argument, it is required if enddest is specified.
• enddest
  A pointer to a pointer to char . The _MOVC5 function sets this output argument to the address of the byte beyond the destination string.

The _MOVPSL function stores the value of the Processor Status Longword (PSL).

The _MOVPSL function has the following format:

void _MOVPSL (void *__psl);

__psl

The address of the location for storing the value of the PSL.

The _MTPR function loads a value into one of the special processor registers. It is a privileged function.

The _MTPR function has the following format:

int _MTPR (int src, int register_num);

src

The value to store into the processor register.

register_num

The number of a privileged register to be updated.

The return value is the V condition flag from the Processor Status Longword (PSL).

6.2.2.17 Probe Read Accessibility ( _PROBER)

The _PROBER function checks to see if you can read the first and last byte of the given address and length pair.

The _PROBER function has the following format:

typedef enum { _probe_not_accessible, _probe_accessible} _PROBE_STATUS; _PROBE_STATUS _PROBER (char __mode, unsigned short __length, const void *__address);

__mode

The processor mode used for checking the access.

__length

The length of the memory segment, in bytes. The length must be a value from 0 to 65,535.

On OpenVMS Alpha systems, this parameter is the offset to the last byte in the memory segment, and not the memory segment length.

__address

The pointer to the memory segment to be tested for read access.

There are two possible return values:

• _probe_not_accessible (0) if one or both bytes are not accessible
• _probe_accessible (1) if both bytes are accessible

The _PROBEW function checks the write accessibility of the first and last byte of the given address and length pair.

The _PROBEW function has the following format:

typedef enum { _probe_not_accessible, _probe_accessible} _PROBE_STATUS; _PROBE_STATUS _PROBEW (char __mode, unsigned short __length, const void *__address);

__mode

The processor mode used for checking the access.

__length

On OpenVMS VAX systems, the length of the memory segment, in bytes. The length must be a value from 0 to 65,535.

On OpenVMS Alpha systems, this parameter is the offset to the last byte in the memory segment, and not the memory segment length.

__address

The pointer to the memory segment to be tested for write access.

There are two possible return values:

• _probe_not_accessible (0) if one or both bytes are not accessible
• _probe_accessible (1) if both bytes are accessible

The _READ_GPR function returns the value of a general-purpose register.

The _READ_GPR function has the following format:

int _READ_GPR (int register_num);

register_num

An integer constant expression giving the number of the general-purpose register to be read.

The return value is the value of the general-purpose register.

6.2.2.20 Remove Entry from Queue at Head Interlocked ( _REMQHI)

The _REMQHI function removes the first entry from the queue in an indivisible manner. This operation is interlocked against similar operations by other processors or devices in the system.

The _REMQHI function has the following format:

typedef enum { _remqi_removed_more, _remqi_not_removed, _remqi_removed_empty, _remqi_empty} _REMQI_STATUS; _REMQI_STATUS _REMQHI (void *__head, void *__removed_entry);

__head

A pointer to the queue header. The header must be aligned on a quadword boundary. (You can achieve alignment using the _align or __align storage-class modifier.)

__removed_entry

A pointer that _REMQHI sets to point to the removed entry.

There are four possible return values:

• _remqi_removed_more (0) if the entry was removed and the queue has remaining entries
• _remqi_not_removed (1) if the entry could not be removed because the secondary interlock failed
• _remqi_removed_empty (2) if the entry was removed and the queue is now empty
• _remqi_empty (3) if the queue was empty

The _REMQTI function removes the last entry from the queue in an indivisible manner. This operation is interlocked against similar operations by other processors or devices in the system.

The _REMQTI function has the following format:

typedef enum { _remqi_removed_more, _remqi_not_removed, _remqi_removed_empty, _remqi_empty} _REMQI_STATUS; _REMQI_STATUS _REMQTI (void *__head, void *__removed_entry);

__head

A pointer to the queue header. The header must be aligned on a quadword boundary. (You can achieve alignment using the _align or __align storage-class modifier.)

__removed_entry

A pointer to a pointer that _REMQTI sets to point to the removed entry.

There are four possible return values:

• _remqi_removed_more (0) if the entry was removed and the queue has remaining entries
• _remqi_not_removed (1) if the entry could not be removed because the secondary interlock failed
• _remqi_removed_empty (2) if the entry was removed and the queue is now empty
• _remqi_empty (3) if the queue was empty

The _REMQUE function removes an entry from a queue.

The _REMQUE function has the following format:

typedef enum { _remque_removed_more, _remque_removed_empty, _remque_empty} _REMQUE_STATUS; _REMQUE_STATUS _REMQUE (void *__entry, void *__removed_entry);

__entry

A pointer to the queue entry to be removed.

__removed_entry

A pointer to a pointer that _REMQUE sets to the address of the entry removed from the queue.

There are three possible return values:

• _remque_removed_more (0) if the entry was removed and the queue has remaining entries
• _remque_removed_empty (1) if the entry was removed and the queue is now empty
• _remque_empty (2) if the queue was empty

The _SCANC function locates the first character in a string with the desired attributes. The attributes are specified through a table and a mask.

The _SCANC function has the following format:

unsigned short _SCANC (unsigned short __length, const char *__string, const char *__table, char __mask, ...);

__length

The length of the string to be scanned, in bytes. The length must be a value from 0 to 65,535.

__string

A pointer to the string to be scanned.

__table

A pointer to the table.

__mask

The mask.

...

An optional match argument, which is a pointer to a pointer to char . The _SCANC function sets this output argument to the address of the byte that matched. (If no match occurs, this argument is set to the address of the byte following the string.)

The return value is the number of bytes remaining in the string if a match was found; otherwise, the return value is 0.

6.2.2.24 Skip Character ( _SKPC)

The _SKPC function locates the first character in a string that does not match the target character.

The _SKPC function has the following format:

unsigned short _SKPC (char __target, unsigned short __length, const char *__string, ... );

__target

The target character.

__length

The length of the string, in bytes. The length must be a value from 0 to 65,535.

__string

A pointer to the string to be scanned.

...

An optional position argument, which is a pointer to a pointer to char . The _SKPC function sets this output argument to the address of the nonmatching character. (If all the characters in the string match, this argument is set to the address of the first byte beyond the string.)

The return value is the number of bytes remaining in the string if an unequal byte was located; otherwise, the return value is 0.

6.2.2.25 Span Characters ( _SPANC)

The _SPANC function locates the first character in a string without certain attributes. The attributes are specified through a table and a mask.

The _SPANC function has the following format:

unsigned short _SPANC (unsigned short __length, const char *__string, const char *__table, char __mask, ...);

__length

The length of the string, in bytes. The length must be a value from 0 to 65,535.

__string

A pointer. It points to the string to be scanned.

__table

A pointer to the table.

__mask

The mask.

...

An optional position argument, which is a pointer to a pointer to char . The _SPANC function sets this output argument to the address of the nonmatching character. (If all the characters in the string match, this argument is set to the address of the first byte beyond the string.)

The return value is the number of bytes remaining in the string if a match was found; otherwise, the return value is 0.