Novell Doc: NDK: Libraries for C (LibC), Volume 1

20.2 POSIX Flags

The following flags are used by the POSIX functions and structures:

20.2.1 Command Modes

The fcntl function uses the following flags in the cmd parameter. They are defined in the fcntl.h file and are described in the following table. The locking flags are for advisory locks, which can only be used by threads within a single virtual machine and cannot be shared with another virtual machine.

Constant	Value	Description
F_GETFL	1	Gets the file status flags (O_APPEND, O_DSYNC, O_NONBLOCK, O_RSYNC, and O_SYNC) and the file access modes (O_RDONLY, O_WRONLY, and O_RDWR). The third parameter is not used.
F_SETFL	2	Sets the file status flags (O_APPEND, O_DSYNC, O_NONBLOCK, O_RSYNC, and O_SYNC). The third parameter of fcntl must be one of these flags or FNDELAY (0x0004), which specifies non blocking I/O.
F_DUPFD	3	Duplicates the file descriptor. The third parameter of fcntl must be an integer, specifying a value that the duplicate file descriptor must equal or be greater than.
F_GETFD	4	Gets the file descriptor flags (FD_CLOEXEC). The third parameter is not used.
F_SETFD	5	Sets the file descriptor flags. The third parameter must be an integer and must be set to either FD_CLOEXEC or 0.
F_SETLK	6	Sets or clears the record lock, specified by the third parameter of fcntl, which is a pointer to an flock structure. If the lock cannot be set, the fcntl function returns immediately with a return value of -1.
F_GETLK	7	Gets the first record lock specified by the third parameter of the fcntl function, which is a pointer to an flock structure. The information retrieved overwrites the information passed in the flock structure. If no lock is found that would prevent this lock from being created, the structure is left unchanged except for the lock type, which is set to F_UNLCK.
F_SETLKW	8	Sets or clears the record lock, specified by the third parameter of fcntl, which is a pointer to an flock structure. This is the same as F_SETLK except that it waits if lock cannot be currently granted.
F_SETLK64	16	Sets or clears the record lock (64-bit), specified by the third parameter of fcntl, which is a pointer to an flock64 structure. If the lock cannot be set, the fcntl function returns immediately with a return value of -1.
F_GETLK64	17	Gets the first record lock (64-bit) specified by the third parameter of the fcntl function, which is a pointer to an flock64 structure. The information retrieved overwrites the information passed in the flock64 structure. If no lock is found that would prevent this lock from being created, the structure is left unchanged except for the lock type, which is set to F_UNLCK.
F_SETLKW64	18	Sets or clears the record lock(64-bit), specified by the third parameter of fcntl, which is a pointer to an flock64 structure. This is the same as F_SETLK64 except that it waits if lock cannot be currently granted.

20.2.2 Directory Entry Types

The following flags have been defined for the d_type field of the DIR structure. The DT_ flags are defined in the dirent.h file, and the S_IF flags in the sys/mode.h file.

Constant dirent.h	Constant sys/mode.h	Value	Description
DT_UNKNOWN		0	Specifies that the entry is an unknown entry type.
DT_TTY		1	Specifies that the entry is a console. This won't occur on the NetWare® operating system.
DT_FIFO	S_IFIFO	0x1000	Specifies that the entry is a first-in/first-out device, either a FIFO or a pipe.
DT_CHR	S_IFCHR	0x2000	Specifies that the entry is a character-special file. On NetWare, it is used for the console.
DT_DIR	S_IFDIR	0x4000	Specifies the entry is a subdirectory.
DT_BLK	S_IFBLK	0x6000	Specifies that the entry is a blocking device. This in not used on a NetWare file system.
DT_REG	S_IFREG	0x8000	Specifies that the entry is a normal file.
DT_LNK	S_IFLNK	0xA000	Specifies that the entry is a symbolic or hard link. This won’t occur on a NetWare file system.
DT_SOCK	S_IFSOCK	0xC000	Specifies that the entry is a socket. This won't occur on a NetWare file system.

20.2.3 File Access Modes and NetWare Attributes

The various access mode constants are defined in the sys/mode.h header file. These constants are resolved using a bitwise OR, and they set the mode parameter in the chmod, creat, fchmod, mkdir, mkfifo, and open (when oflag is set to O_CREAT) functions. The stat and fstat functions return the current value of mode.

On NetWare file systems, you cannot use the mode parameter to set file system permissions or rights. The file or directory inherits its rights from the user creating it, its path, and NetWare trustee assignments. You can use the mode parameter to set file and directory attributes with either POSIX permission modes or with NetWare attribute flags.

Permission Modes

The permission modes have the following meanings on the NetWare file systems:

Permission Mode	Description
rwx	Flags the file as read/write and sets no NetWare attribute bits.
r	Sets the read only attribute.
rx	Sets the read only attribute.
rw	Flags the file as read/write and sets no NetWare attribute bits.
w	Flags the file as read/write and sets no NetWare attribute bits.
wx	Flags the file as read/write and sets no NetWare attribute bits.
x	Sets the read only and the execute attribute.

The following constants can be OR'd together to create the permission mode.

User Constants	Group Constants	Other Constants	Permission Mode
S_IRWXU	S_IRWXG	S_IRWXO	rwx
S_IRUSR S_IREAD	S_IRGRP	S_IROTH	r
S_IWUSR S_IWRITE	S_IWGRP	S_IWOTH	w
S_IXUSR S_IEXEC	S_IXGRP	S_IXOTH	x

The permission modes are OR'd, not within a type (such as user), but with all types (user, group, and other). For example the OR of the following flags (S_IRUSR | S_IWGRP | S_IXOTH) has the same effect as any one of the following flags: S_IRWXU, S_IRWXG, or S_IRWXO.

If the permission mode equates to 0 and the M_A_BITS_SIGNIFICANT bit is not set, the read only attribute is set.

NetWare Attribute Flags

The M_A_BITS_SIGNIFICANT bit signals LibC that you are using the mode parameter to set NetWare attributes:

If the M_A_BITS_SIGNIFICANT bit is set, the NetWare attribute bits are used to set attributes in addition to the permission modes. If the permission mode equates to 0, the NetWare attribute bits can be used to both clear and set attributes because any attribute not included in the bit mask is cleared.
If the M_A_BITS_SIGNIFICANT bit is not set, the NetWare specific flags are not examined and only the permission modes are used to set attributes.

The following constants are used to set attributes:

Constant	Value	Description
M_A_RDONLY	0x00010000	Entry is read-only entry.
M_A_HIDDEN	0x00020000	Entry is a hidden entry.
M_A_SYSTEM	0x00040000	Entry is a system entry.
M_A_SUBDIR	0x00080000	S_IFDIR
M_A_ARCH	0x00100000	File has been archived.
M_A_SHARE	0x00200000	File is shared.
M_A_TRANS	0x00400000	Track file transactions.
M_A_IMMPURG	0x00800000	Purge deleted file immediately.
M_A_NORENAM	0x01000000	Inhibit renaming.
M_A_NODELET	0x02000000	Inhibit deletion.
M_A_NOCOPY	0x04000000	Inhibit copying.
M_A_IMMCOMPRESS	0x08000000	Compress immediately.
M_A_FILE_COMPRESSED	0x10000000	File is compressed.
M_A_DONT_COMPRESS	0x20000000	Inhibit compression.
M_A_CANT_COMPRESS	0x40000000	Prevent the file from being compressed.
M_A_BITS_SIGNIFICANT	0x80000000	Use the attribute settings found in the upper 16 bits.

20.2.4 File Control Open Modes

The open mode is established as a combination of the bits defined in the fcntl.h header file. Of the following first three values, only one can be set. The other flags can be ORed to one of these first three values.

Constant	Value	Description
O_RDONLY	0x00000000	Allows users to access the file only for reading. This flag cannot be ORed with O_WRONLY or O_RDWR.
O_WRONLY	0x00000001	Allows users to access the file only for writing. This flag cannot be ORed with O_RDONLY or O_RDWR.
O_RDWR	0x00000002	Allows user to access the file for reading and writing. This flag cannot be ORed with O_WRONLY or O_RDONLY.
O_ACCMODE	0x00000003	Specifies the access flags mask. You use this mask to isolate the read and write mode of the file by ANDing this mask to one of the three previous flags (O_RDONLY, O_WRONLY, or O_RDWR).
O_reserved1	0x00000004	Reserved.
O_reserved2	0x00000008	Reserved.
O_APPEND	0x00000010	Causes each record that is written to be written at the end of the file.
O_CREAT	0x00000020	Has no effect unless combined with the O_EXCL flag.
O_TRUNC	0x00000040	Causes the file to be truncated to contain no data when the file exists; has no effect when the file does not exist. O_TRUNC must be ORed with write access to truncate a file: O_TRUNC \| O_RDWR O_TRUNC \| O_WRONLY
O_EXCL	0x00000080	Opens the file exclusively. If set with the O_CREAT flag, causes a check for the existence of the file. If the file exists, the open fails.
O_NOCTTY	0x00000100	Not supported.
O_BINARY	0x00000200	Causes the data to be transmitted unchanged. If not set, the file is in text mode and carriage- return/line-feed pairs are translated to line feeds on input, and line feeds are translated to carriage-return/line-feed pairs on output.
O_NDELAY	0x00000400	Must be used to open a FIFO or special character file. FIFO. Has the following effects if O_RDONLY or O_WRONLY is also set: An open for read-only returns immediately and without delay. An open returns an error if no process currently has the file opened for reading Has the following effects if not set and O_RDONLY or O_WRONLY is set: An open for read-only waits until a process has opened the file for writing. An open for write-only waits until a process has opened the file for reading. Special Character File. Has the following effects if the file supports non-blocking opens: If O_NDELAY is set, the open returns without waiting for the device to be ready or available. If O_NDELAY is not set, the open waits until the device is ready and available before returning.
O_reserved3	0x00000800	Reserved.
O_SYNC	0x00001000	Causes the process to block until all data and all file attributes are written to disk.
O_DSYNC	0x00002000	Causes the process to block until all data and file attributes used in data access are written to disk. If set with O_SYNC, this flag has no affect.
O_RSYNC	0x00004000	Must be set with O_SYNC or O_DSYNC to have effect. Writes are performed according to the O_SYNC or O_DSYNC flag. Has the following effects on reads: If O_DSYNC is set, reads the data and the data access attributes and waits until the memory image is the same as the disk image. If O_SYNC is set, reads the data and all file attributes and waits until the attributes are updated to reflect the read operation.
O_NONBLOCK	O_NDELAY	Has the same functionality as O_NDELAY.
FD_CLOEXEC	0x00008000	Closes the file descriptor on execution. Used by fcntl.
O_UPDATE	0x00010000	Ensures that the size and date information is updated on the disk as a file on a traditional volume is written to.
O_FIFO	0x00100000	Opening one end of a FIFO. This is non-standard flag.

20.2.5 I/O Control Flags for FIFOs

The following flags can be passed in the request parameter of the ioctl function. The flags are defined in the sys/ioctl.h file

Flag	Value	Description
I_NREAD	0	Counts the number of data bytes in data blocks in the first message on the stream-head read queue, and places this value in the location pointed to by the arg parameter. The return value for the command is the number of messages on the stream-head read queue. On failure, errno is set. For a pipe file, counts the number of data bytes left to read on the descriptor before the read function blocks.
I_NWRITE	1	Counts the number of data bytes that may be written on a pipe descriptor before the write function blocks. Similar to I_NREAD.
I_SETBUF	2	Exchanges the buffer currently underlying the pipe for one of a different size. The pipe becomes empty and cleared with respect to data read or written.
I_TIMESTAMP	3	Determines whether timestamp information is maintained on when the entity was last read from, written to, or accessed. The default is not to maintain this information because it adds overhead. For it to be maintained, you must include this flag.

20.2.6 I/O Control Flags for Sockets

The following flags can be passed in the request parameter of the ioctl function. The FIO flags are defined in the sys/filio.h file and SIO flags in the sys/sockio.h file.

Flag	Value	Description
FIONREAD	1	Reads the number of bytes currently in the socket receive buffer. The value is returned in the third parameter of ioctl.
FIONBIO	2	Sets and clears the nonblocking flag for sockets, depending upon the integer value of the third argument passed to ioctl. A nonzero value indicates the flag is set; a zero value indicates the flag is clear.
FIOGETNBIO	3	Gets the nonblocking status of the socket. The status is returned in the third parameter of ioctl. A nonzero value indicates the flag is set; a zero value indicates the flag is clear.
SIOCATMARK	8	Supported for TCP sockets. Returns a nonzero value if the socket's read pointer is currently at the out-of-band mark. A zero value indicates the read pointer is not at the out-of-band mark. The value is returned in the third parameter of ioctl.
SIOCDGRAMSIZE	500	Supported for Raw IP sockets (NetWare specific). Returns the size of the datagram received in bytes. The value is returned in the third parameter of ioctl. The next read call returns this datagram to the application.

20.2.7 Name Space Flags

The fgetstat_with_namespace, getstat_with_namespace, set_pathname_format, and other functions use the name space flags to set the format for returning path and file names. They are defined in the fsio.h file.

Flag	Value	Description
SHORT_NAMES	0	Specifies the DOS 8.3 format
MACINTOSH_NAMES	1	Macintosh name space
NFS_NAMES	2	UNIX or NFS name space
FTAM_NAMES	3	FTAM name space
LONG_NAMES	4	Default long name space
NT_NAMES	5	Windows NT name space

20.2.8 Path Configuration Variables

The fpathconf and pathconf functions use these path configuration variables to return information about file system limits for such items as pathnames and filenames. These values are defined in sys/unistd.h file.

Flag	Value	Description
_PC_LINK_MAX	1	Specifies the maximum number of links to the file.
_PC_MAX_CANON	2	Specifies the maximum number of bytes in an input line. This value only applies to a terminal devices.
_PC_MAX_INPUT	3	Specifies the maximum number of bytes allowed in an input queue. This value only applies to a terminal device.
_PC_NAME_MAX	4	Specifies the maximum number of bytes in a filename, not including the null-terminating character. This value only applies to a directory file.
_PC_PATH_MAX	5	Specifies the maximum number of bytes in a pathname, not including a null-terminating character.
_PC_PIPE_BUF	6	Specifies the maximum number of bytes guaranteed to be written automatically. This value only applies to a FIFO.
_PC_NO_TRUNC	7	Returns 0 if component names are truncated. This value only applies to a directory file.
_PC_VDISABLE	8	Specifies the disabling character. Returns 0 if none is defined. This value only applies to a terminal device.
_PC_CHOWN_RESTRICTED	9	Returns 0 if chown has restrictions.

20.2.9 Process Flags

The following flags are used by the processle and processve functions to specify how a process is to be started. The flags can be OR's together.

Flag	Value	Description
PROC_DETACHED	0x00000001	Create as a detached process.
PROC_CURRENT_SPACE	0x00000004	Use the current address space of the parent.
PROC_MEMORY_DEBUG	0x00000008	Load as if the load -m command was issued. This flag should only be used during development and debugging. It should never be part of a shipping product, because it kills performance. However, you will find it very useful during development and debugging for the following types of problems: Catches memory overruns. It causes every memory allocation to be justified to the end of the memory page with a guard page mapped in as the next page. If the end of the memory block is every overwritten, a page fault occurs and the server abends at the point memory corruption begins rather than long time afterwards. Catches writes to already freed memory. Because each allocation has its own page and the page associated with each allocation is mapped out during the call to free the memory, any future writes to the page results in a page fault and a server abend at the point memory corruption begins.
PROC_LOAD_SILENT	0x00000010	Load silently, without any console messages.
PROC_INHERIT_CWD	0x00000020	Start the child process in the same current working directory as the parent.
PROC_INHERIT_ID	0x00000040	Allow the child process to inherit the identity of the parent.

20.2.10 Request Flags for Entry Status

The following flags are used by the fgetstat and getstat functions to specify which fields in the stat structure are filled in. The flags can be OR's together.

Flag	Value	Description
ST_FLAGS_BIT	0x00000001	Specifies the open flags for the entry (st_flags field) and returns O_RDONLY, O_WRONLY, or O_RDWR.
ST_MODE_BIT	0x00000002	Specifies the file mode (st_mode field). For a list of possible modes, see File Access Modes and NetWare Attributes.
ST_GEN_BIT	0x00000004	Specifies the generation number of the inode (st_gen field). This number is not used in NetWare file systems.
ST_INO_BIT	0x00000008	Specifies the directory entry number (st_ino field).
ST_DEV_BIT	0x00000010	Specifies the volume number (st_dev field).
ST_RDEV_BIT	0x00000020	Specifies the device type (st_rdev field). This is always 0 on NetWare file systems.
ST_SIZE_BIT	0x00000040	Specifies the total file size in bytes (st_size). Only valid for files.
ST_BLOCKS_BIT	0x00000080	Specifies the number of blocks allocated to the file (st_blocks field).
ST_BLKSIZE_BIT	0x00000100	Specifies the block allocation size (st_blksize field). Valid only for files.
ST_NLINK_BIT	0x00000200	Specifies the count of hard links (st_nlink field). Always 1 on NetWare file systems.
ST_UID_BIT	0x00000400	Specifies the object ID of the owner (st_uid field).
ST_GID_BIT	0x00000800	Specifies the group ID (st_gid field). Always 0 on NetWare file systems.
ST_BID_BIT	0x00001000	Specifies the ID of the object that last archived the entry (st_bid field).
ST_MID_BIT	0x00002000	Specifies the ID of the object that last modified the entry (st_mid field).
ST_ATIME_BIT	0x00004000	Specifies the last time the file was accessed (st_atime field). Not used for directories.
ST_MTIME_BIT	0x00008000	Specifies the last time the entry was modified (st_mtime field).
ST_CTIME_BIT	0x00010000	Specifies when the attributes of the file last changed (st_ctime field).
ST_BTIME_BIT	0x00020000	Specifies when the entry was last archived (st_btime field).
ST_STAT_BITS	0x0003FFFF	Specifies that all normal stat structure fields should be returned, which includes all fields except the st_name and the st_rights fields.
ST_RIGHTS_BIT	0x00040000	Specifies the effective rights of the caller to the entry (st_rights field).
ST_NAME_BIT	0x00080000	Specifies the name of the entry (st_name field).
ST_NS_BIT	0x00100000	Specifies that name be returned in the requested name space. Used by the fgetstat_with_namespace and getstat_with_namespace functions.

20.2.11 System Configuration Values

The sysconf function uses the following values to return the current numeric value of configurable system limits. These values are defined in the sys/unistd.h file. Only the values that currently return configuration information are listed below. The others return -1.

Constant	Value	Description
_SC_VERSION	1	Indicates which version of the POSIX standard has been implemented.
_SC_CLK_TCK	7	Specifies the number of clock-ticks per second.
_SC_GETGR_R_SIZE_MAX	9	Specifies the maximum size of the group entry buffer.
_SC_GETPW_R_SIZE_MAX	10	Specifies the maximum size of the password entry buffer.
_SC_PAGESIZE	17	Specifies the size of a physical memory page in bytes. This is the same as _SC_PAGE_SIZE.
_SC_SEM_VALUE_MAX	19	Specifies the maximum value a semaphore can have.
_SC_THREAD_KEYS_MAX	23	Specifies the maximum number of keys per process.
_SC_THREAD_STACK_MIN	24	Specifies the minimum number of bytes allowed for a thread stack.
_SC_THREAD_THREADS_MAX	25	Specifies the maximum number of threads a process can create.
_SC_TTY_NAME_MAX	27	Specifies the maximum length of a terminal device name.
_SC_TZNAME_MAX	28	Specifies the maximum number of bytes in a time zone name.
_SC_FSYNC	30	Indicates support for file synchronization.
_SC_MAPPED_FILES	32	Indicates support for memory mapped files.
_SC_MEMLOCK	33	Indicates support for process memory locking.
_SC_MEMLOCK_RANGE	34	Indicates support for range memory locking.
_SC_SAVED_IDS	40	Indicates whether each process has a saved user ID and a saved group ID. This used by the following functions: exec, kill, seteuid, seteguid, setgid, and setuid.
_SC_SEMAPHORES	41	Indicates support for semaphores.
_SC_SHARED_MEMORY_OBJECTS	42	Indicates support for shared memory objects.
_SC_THREADS	45	Indicates support for thread options.
_SC_THREAD_ATTR_STACKADDR	46	Indicates whether the address attribute option for a thread address is supported: 1 = supported and -1 = unsupported.
_SC_THREAD_ATTR_STACKSIZE	47	Indicates whether you can set the stack size for a thread: 1 = supported and -1 = unsupported.
_SC_THREAD_SAFE_FUNCTIONS	52	Indicates whether the thread safe option is supported: 1 = supported and -1 = unsupported.
_SC_HOST_NAME_MAX	53	Specifies the maximum number of bytes allowed in a host name.
_SC_READER_WRITER_LOCKS	54	Indicates support for reader-writer locks and functions.
_SC_REGEXP	55	Indicates support for regular expressions and functions.
_SC_PHYS_PAGES	56	Specifies the total number of pages of physical memory in the system.
_SC_AVPHYS_PAGES	57	Specifies the total number of pages of physical memory not currently in use by the system.
_SC_IPV6	58	Indicates support for Internet Protocol Version 6.
_SC_PAGE_SIZE	59	Specifies the size of a physical memory page in bytes. This is the same as _SC_PAGESIZE

20.2.12 System Configuration Strings

The confstr function uses the following flags to return system configuration strings. These flags are defined in the sys/unistd.h file.

Flag	Value	Description
_CS_PATH	1	The setting for the PATH environment variable.
_CS_HOSTNAME	2	The name of this node in the network. This corresponds to the nodename field in the utsname structure.
_CS_RELEASE	3	Operating system release. This corresponds to the release field in the utsname structure.
_CS_VERSION	4	Version of the operating system. This corresponds to the version field in the utsname structure.
_CS_MACHINE	5	The kind of hardware used by this node. This corresponds to the machine field in the utsname structure.
_CS_ARCHITECTURE	6	The instruction set architecture for the CPU of this node.
_CS_HW_SERIAL	7	The serial number associated with the hardware.
_CS_HW_PROVIDER	8	The name of the hardware manufacturer.
_CS_SYSNAME	9	The name of the operating system. This corresponds to the sysname field in the utsname structure.