Open System Services System Calls Reference Manual

Add to my manuals
820 Pages

advertisement

Open System Services System Calls Reference Manual | Manualzz

Open System Services

System Calls

Reference Manual

Abstract

This manual documents part of the HP NonStop Open System Services (OSS) application program interface. It is written for system and application programmers.

Product Version

N.A.

Supported Release Version Updates (RVUs)

This manual supports G06.25 and H06.03 and all subsequent G-series and H-series release version updates until otherwise indicated by its replacement publication.

Part Number Published

527186-003 July 2005

Document History

Part Number Product Version

527186-003 N/A

Published

July 2005

What is New in This Manual .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

New Functions

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Changed Functions .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Changes in Miscellaneous Topics

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Changes in Files

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

General Changes

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

About This Manual

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Audience .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Purpose

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Document Usage

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Reference Page Format

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Related Documents .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Reference Section Numbers

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Typographic and Keying Conventions

.

.

.

.

.

.

.

.

.

.

.

.

.

Section 1. System Functions (a - d)

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

accept .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

access .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

bind

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

chdir

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

chmod

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

chown

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

chroot .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

close

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

connect

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

creat

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

dup

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

dup2

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Section 2. System Functions (e)

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

exec

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

execl

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

execle .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

execlp

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

execv .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

execve

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

execvp

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

_exit

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Section 3. System Functions (f - i)

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

527186-003 Hewlett-Packard Company xviii xix

1-11

1-14

1-18

1-22

1-1

1-2

1-5

1-8

1-25

1-27

1-31

1-38

1-40

2-1

2-2

2-3

2-11

2-19

2-27

2-35

2-43

2-51

3-1 xvi xvi xvi xvii xiv xiv xv xvi xii xiii xi xi iii

OSS System Calls Reference Manual fcntl

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

fork

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

fstat

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

fstatvfs

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

fsync

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

ftruncate

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

getegid

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

geteuid

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

getgid .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

getgroups

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

gethostname .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

getlogin

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

getpeername .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

getpgid

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

getpgrp

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

getpid .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

getppid

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

getpriority

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

getsockname .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

getsockopt

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

gettimeofday

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

getuid .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

ioctl

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Section 4. System Functions (k - m)

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

kill

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

link

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

listen

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

lseek

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

lstat

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

mkdir .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

mknod

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

msgctl

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

msgget

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

msgrcv

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

msgsnd

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Section 5. System Functions (n - p)

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

nice

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

open

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pipe

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_atfork

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_attr_destroy

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_attr_getdetachstate

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_attr_getguardsize_np

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_attr_getinheritsched

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_attr_getschedparam

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_attr_getschedpolicy

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_attr_getstackaddr .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_attr_getstacksize .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_attr_init

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_attr_setdetachstate

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_attr_setguardsize_np .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_attr_setinheritsched

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_attr_setschedparam

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_attr_setschedpolicy

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

iv Hewlett-Packard Company 527186-003

5-21

5-22

5-23

5-24

5-25

5-26

5-28

5-30

5-1

5-2

5-4

5-14

5-16

5-18

5-19

5-20

5-32

5-34

5-36

4-11

4-13

4-22

4-27

4-1

4-2

4-5

4-9

4-33

4-36

4-39

4-42

3-37

3-38

3-39

3-40

3-41

3-43

3-44

3-45

3-2

3-9

3-14

3-23

3-31

3-33

3-35

3-36

3-46

3-47

3-49

3-51

3-57

3-59

3-60

pthread_attr_setstacksize

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_cancel

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_cleanup_pop

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_cleanup_push .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_cond_broadcast

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_cond_destroy .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_cond_init

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_cond_signal

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_cond_signal_int_np

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_cond_timedwait

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_cond_wait .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_condattr_destroy .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_condattr_init

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_create

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_delay_np

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_detach

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_equal

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_exit .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_get_expiration_np

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_getattr_np .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_getconcurrency

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_getschedparam

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_getspecific .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_join .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_key_create .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_key_delete .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_kill

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_lock_global_np

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_mutex_destroy

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_mutex_init .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_mutex_lock

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_mutex_trylock

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_mutex_unlock .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_mutexattr_destroy

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_mutexattr_getkind_np

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_mutexattr_init .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_mutexattr_setkind_np

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_once

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_self

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_setcancelstate .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_setcanceltype .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_setconcurrency

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_setschedparam

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_setspecific .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_sigmask

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_testcancel

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pthread_unlock_global_np

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Section 6. System Functions (r)

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

read

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

readlink

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

readv

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

recv

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

recvfrom .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

recvmsg

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Contents

5-70

5-72

5-73

5-75

5-76

5-77

5-79

5-80

5-60

5-61

5-62

5-63

5-64

5-65

5-67

5-68

5-47

5-48

5-50

5-52

5-53

5-55

5-58

5-59

5-37

5-38

5-40

5-41

5-42

5-43

5-44

5-46

5-92

5-94

5-95

5-97

5-98

5-100

5-101

5-81

5-82

5-83

5-84

5-86

5-88

5-89

5-90

6-1

6-2

6-6

6-9

6-13

6-16

6-19

527186-003 Hewlett-Packard Company v

OSS System Calls Reference Manual rename

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

rename_guardian

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

rename_oss

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

rmdir

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Section 7. System Functions (s and S)

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

sched_get_priority_max

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

sched_get_priority_min

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

sched_yield

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

select .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

semctl

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

semget

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

semop .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

send

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

sendmsg

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

sendto

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

setgid .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

setpgid

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

setsid .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

setsockopt

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

setuid .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

shmat .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

shmctl

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

shmdt .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

shmget

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

shutdown .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

sigaction

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

sigpending

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

sigprocmask .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

sigsuspend

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

sockatmark

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

socket .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

socketpair

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

socket_transport_name_get

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

socket_transport_name_set

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_accept

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_awaitio

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_close .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_connect

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_fclose

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_fd_read_ready

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_fd_write_ready .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_fflush .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_fgetc .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_fgets

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_fgetwc

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_FileIOHandler_p

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_fork

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_fprintf

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_fputc .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_fputs .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_fputwc

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_fread .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_fwrite

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_generateTag .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

6-23

6-24

6-26

6-32

7-67

7-69

7-71

7-75

7-79

7-81

7-83

7-84

7-45

7-48

7-51

7-53

7-58

7-60

7-64

7-65

7-22

7-25

7-29

7-33

7-34

7-36

7-37

7-44

7-5

7-10

7-15

7-18

7-1

7-2

7-3

7-4

7-94

7-95

7-96

7-97

7-98

7-99

7-100

7-101

7-102

7-103

7-86

7-87

7-88

7-89

7-90

7-91

7-92

7-93 vi Hewlett-Packard Company 527186-003

527186-003 spt_getc

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_getchar

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_gets

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_getTMFConcurrentTransactions .

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_getw

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_getwc

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_getwchar

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_INITRECEIVE .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_interrupt .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_interruptTag

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_OSSFileIOHandler_p .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_printf .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_putc

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_putchar

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_puts

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_putw .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_putwc

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_putwchar

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_read

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_readv .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_RECEIVEREAD

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_recv

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_recvfrom

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_recvmsg .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_regFile

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_regFileIOHandler

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_regOSSFileIOHandler

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_regPathsendFile

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_regPathsendTagHandler

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_regTimerHandler

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_REPLYX

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_select

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_send

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_sendmsg .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_sendto

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_setOSSFileIOHandler .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_setTMFConcurrentTransactions .

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_sleep .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_system

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_TimerHandler_p

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

SPT_TMF_GetTxHandle

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

SPT_TMF_Init

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

SPT_TMF_SetTxHandle

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_unregFile

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_unregOSSFileIOHandler .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_unregPathsendTagHandler

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_usleep

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_vfprintf

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_vprintf

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_waitpid

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_wakeup

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_write .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spt_writev

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

stat

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

statvfs

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Hewlett-Packard Company

Contents

7-146

7-147

7-148

7-149

7-150

7-151

7-152

7-153

7-138

7-139

7-140

7-141

7-142

7-143

7-144

7-145

7-154

7-155

7-156

7-157

7-158

7-159

7-169

7-129

7-130

7-131

7-132

7-133

7-135

7-136

7-137

7-120

7-121

7-122

7-123

7-124

7-126

7-127

7-128

7-112

7-113

7-114

7-115

7-116

7-117

7-118

7-119

7-104

7-105

7-106

7-107

7-108

7-109

7-110

7-111 vii

OSS System Calls Reference Manual symlink

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

SPT_ABORTTRANSACTION

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

SPT_BEGINTRANSACTION

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

SPT_ENDTRANSACTION

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

SPT_RESUMETRANSACTION .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

SPT_SERVERCLASS_DIALOG_ABORT_

.

.

.

.

.

.

.

.

.

.

.

SPT_SERVERCLASS_DIALOG_BEGIN_

.

.

.

.

.

.

.

.

.

.

.

SPT_SERVERCLASS_DIALOG_END_

.

.

.

.

.

.

.

.

.

.

.

.

SPT_SERVERCLASS_DIALOG_SEND_

.

.

.

.

.

.

.

.

.

.

.

.

SPT_SERVERCLASS_SEND_

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

SPT_SERVERCLASS_SEND_INFO_

.

.

.

.

.

.

.

.

.

.

.

.

.

Section 8. System Functions (t)

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

tdm_execve

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

tdm_execvep

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

tdm_fork .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

tdm_spawn

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

tdm_spawnp .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Section 9. System Functions (u)

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

ulimit .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

umask .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

uname

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

unlink .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

utime .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Section 10. System Functions (w)

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

wait

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

waitpid

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

write

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

writev .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Section 11. Files

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

ar

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

core

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

cpio

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

dir .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

float

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

limits .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

math

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

null

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

saveabend

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

signal .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

spthread.h

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

tar .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

termcap

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

termios

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

tty .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Section 12. Miscellaneous

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

ascii

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

environ

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

errno

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

filename

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

hier

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

pathname .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

process_extension_results .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

9-1

9-2

9-4

9-5

9-7

9-11

8-1

8-2

8-16

8-30

8-40

8-56

10-1

10-2

10-7

10-13

10-18

7-178

7-182

7-183

7-184

7-185

7-186

7-187

7-190

7-191

7-194

7-197

11-18

11-19

11-20

11-27

11-35

11-38

11-51

11-57

11-1

11-2

11-3

11-4

11-7

11-8

11-10

11-17

12-1

12-2

12-4

12-21

12-29

12-36

12-38

12-39 viii Hewlett-Packard Company 527186-003

Contents

Permuted Index

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Pindex-1

Index

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Index-1

527186-003 Hewlett-Packard Company ix

OSS System Calls Reference Manual

LIST OF TABLES

Table 3

1. Ignored File Status Flags

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Table 3

2. Guardian File Type Mappings

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

3-3

3-20

Table 4

1. Guardian File Type Mappings

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

4-19

Table 7

1. Guardian File Type Mappings

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

7-165

Table 11

1. cpio Archive File Header Format

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Table 11

2. cpio Archive File Filename Entry Format

.

.

.

.

.

.

.

.

.

.

.

.

Table 11

3. cpio Archive File Data Format .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Table 11

4. cpio.h Header File Macros

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

11-4

11-5

11-5

11-6

Table 11

5. Values for Floating-Point Constants

.

.

.

.

.

.

.

.

.

.

.

.

.

.

11-9

Table 11

6. Values for Floating-Point Constants

.

.

.

.

.

.

.

.

.

.

.

.

.

.

11-15

Table 11

7. Values for Symbolic Constants .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

11-16

Table 11

8. Signals .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

11-22

Table 11

9. tar Archive File Header Block

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

11-35

Table 11

10. Terminal Name Suffixes .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

11-38

Table 11

11. Terminal Capabilities

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

11-39

Table 12

1. ASCII Character Set Octal Values .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

12-2

Table 12

2. ASCII Character Set Hexadecimal Values

.

.

.

.

.

.

.

.

.

.

.

.

Table 12

3. ASCII Character Set Decimal Values .

.

.

.

.

.

.

.

.

.

.

.

.

.

12-2

12-3 x Hewlett-Packard Company 527186-003

What is New in This Manual

This section describes changes made to the Open System Services System Calls

Reference Manual since the 522693-005 edition.

This manual contains information about some of the following G-series development tools, which are not available on H-series servers:

TNS/R native C compiler

TNS/R native C++ compiler

TNS/R native C++ runtime library version 2

SQL/MP for TNS/R native C

SQL/MP Compilation Agent for TNS/R programs

NMCOBOL compiler and nmcobol frontend

ld

nld

noft

TNS/R native pTAL

Continue to use the Enterprise Toolkit or G-series servers for your G-series development tasks.

New Functions

The following reference pages were added to support POSIX threads:

pthread_attr_getstackaddr(2) pthread_getattr_np(2)

SPT_TMF_Init(2)

SPT_TMF_GetTxHandle(2)

SPT_TMF_SetTxHandle(2) spt_fork(2) spt_getTMFConcurrentTransactions(2)

527186-003 Hewlett-Packard Company xi

OSS System Calls Reference Manual

spt_regPathsendFile(2) spt_regPathsendTagHandler(2) spt_setTMFConcurrentTransactions(2) spt_sleep(2) spt_unregPathsendTagHandler(2) spt_usleep(2)

Changed Functions

Information was revised on the following reference pages:

chmod(2)

Added trust bit to possible values for file mode.

execl(2) execle(2)

Added security group list information to resolve Genesis Change

Request 10-050106-4114. Added information for SIG_ABORT and

SIG_DEBUG.

Added security group list information to resolve Genesis Change

Request 10-050106-4114. Added information for SIG_ABORT and

SIG_DEBUG.

execlp(2) execv(2) execve(2) execvp(2) fork(2)

Added security group list information to resolve Genesis Change

Request 10-050106-4114. Added information for SIG_ABORT and

SIG_DEBUG.

Added security group list information to resolve Genesis Change

Request 10-050106-4114. Added information for SIG_ABORT and

SIG_DEBUG.

Added security group list information to resolve Genesis Change

Request 10-050106-4114. Added information for SIG_ABORT and

SIG_DEBUG.

Added security group list information to resolve Genesis Change

Request 10-050106-4114. Added information for SIG_ABORT and

SIG_DEBUG.

Added security group list information to resolve Genesis Change

Request 10-050106-4114.

Added trust bit to possible values for file mode.

fstat(2)

pthread_create(2) Added information about the pthread_attr_default value.

pthread_condattr_init(2) Added information about the pthread_condattr_default value.

pthread_mutexattr_init(2) Added information about the pthread_mutexattr_default value.

xii Hewlett-Packard Company 527186-003

What is New in This Manual

semctl(2)

Added information about waking processes to resolve Genesis Change

Request 10-040510-8757.

sigaction(2)

Added information for SIG_ABORT and SIG_DEBUG. Added information for the SIGUNCP signal.

sigsuspend(2) Added a pointer to the signal(4) reference page.

stat(2)

Added trust bit to possible values for file mode.

tdm_execve(2) Removed pe_heap_max discussion detail and added pointer to C/C++

Programmer’s Guide. Added security group list information to resolve

Genesis Change Request 10-050106-4114. Added information for

SIG_ABORT and SIG_DEBUG. Added information about

process_extension_results(5) reference page.

tdm_execvep(2) Removed pe_heap_max discussion detail and added pointer to C/C++

Programmer’s Guide. Added security group list information to resolve

Genesis Change Request 10-050106-4114. Added information for

SIG_ABORT and SIG_DEBUG. Added information about

process_extension_results(5) reference page.

tdm_fork(2)

Removed pe_heap_max discussion detail and added pointer to C/C++

Programmer’s Guide. Added security group list information to resolve

Genesis Change Request 10-050106-4114. Added information about

process_extension_results(5) reference page.

tdm_spawn(2) Removed pe_heap_max discussion detail and added pointer to C/C++

Programmer’s Guide. Added security group list information to resolve

Genesis Change Request 10-050106-4114. Added information for

SIG_ABORT and SIG_DEBUG. Added information about

process_extension_results(5) reference page.

tdm_spawnp(2) Removed pe_heap_max discussion detail and added pointer to C/C++

Programmer’s Guide. Added security group list information to resolve

Genesis Change Request 10-050106-4114. Added information for

SIG_ABORT and SIG_DEBUG. Added information about

process_extension_results(5) reference page.

uname(2)

Clarified examples and corrected description of version array.

The H-series subvolume name for libraries was corrected throughout.

Changes in Miscellaneous Topics

The following reference page was revised:

environ(5)

Added the ECOBFE, ELD, and CCOMBE environment variables in support of the native TNS/E compilers. Added the

TCPIP_RESOLVER_NAME environment variable in support of dynamic name servers in the OSS environment.

527186-003 Hewlett-Packard Company xiii

OSS System Calls Reference Manual

process_extension_results(5) Added pointer to specific table in Guardian Procedure

Calls Reference Manual.

Changes in Files

Information was revised on the following reference pages:

signal(4)

Information was added for the SIGUNCP signal.

spthread.h(4) Information was added for the new function calls.

General Changes

Library residence information was added to each reference page.

xiv Hewlett-Packard Company 527186-003

About This Manual

The HP NonStop Open System Services (OSS) application program interface (API) provides an open interface for programs to be run with the underlying HP NonStop operating system.

The Open System Services System Calls Reference Manual contains reference pages for

OSS system functions, files, and miscellaneous topics.

The description of the OSS API is divided into system functions (documented in this manual) and library functions (documented in the Open System Services Library Calls

Reference Manual). Functions appear in one manual or the other, based on the logical section number assigned to the reference page for the function. (So that all threadsrelated functions can be described in a single manual, certain HP extensions to the standard POSIX threads functions do not obey this rule.) Refer to Reference Section

Numbers later in this section for an explanation of the logical section numbers.

This division does not imply any restrictions upon the use of the functions described in either manual. The division exists for many reasons, including:

Consistency with the documentation of the Guardian API. The Guardian API for process management and low-level file-system access is documented separately from other portions of the API available to users of a C run-time library.

Consistency with the separation of functions used in some UNIX systems. In those systems, an important distinction exists between the API for code that is to run in kernel space and the API for code that is to run in user space. This distinction is meaningless for users of the OSS API. The HP NonStop operating system does distinguish among code that runs in user code space, code that runs in system code space, and code that runs in library code space, but the distinction does not separate the functions of the OSS API.

Ease of use for the printed version of the material, which would be a multiple-volume manual regardless of organization.

Unless otherwise indicated in the text, discussions of native mode behavior, processes, and so forth apply to both the TNS/R code that runs on G-series systems and to the

TNS/E code that runs on H-series systems. Discussions of TNS or accelerated code behavior in the OSS environment apply only to G-series systems; H-series systems do not support TNS or accelerated code execution in the OSS environment.

527186-003 Hewlett-Packard Company xv

OSS System Calls Reference Manual

Audience

This manual is for system and application programmers who want to use the OSS application program interface provided with the HP NonStop operating system. The manual assumes that the reader is a programmer and is familiar with the C programming language.

Purpose

This manual provides a complete reference to all OSS system functions and their related files and miscellaneous topics.

Document Usage

This manual contains a portion of the online manual reference (man) pages. These reference pages are divided among 12 sections, as follows:

Sections 1 through 10 contain reference pages for OSS system functions. These reference pages reside in the cat2 or cat3 directory and are sorted alphabetically.

Section 11 contains reference pages for some OSS header and special files. These reference pages reside in the cat4 and cat7 directories and are sorted alphabetically.

Section 12 contains reference pages for some miscellaneous OSS topics. These reference pages reside in the cat5 directory and are sorted alphabetically.

Reference Page Format

The reference pages for functions, files, and miscellaneous topics in this manual use the following format. If a heading has no contents for a particular reference page, it is omitted.

NAME

LIBRARY

Function, file, or miscellaneous topic name and purpose.

Library containing the function. The library is identified in terms of the | run-time environment in which the compiled application must run. For | example, an "H-series native Guardian process" must use the specified library when the c89 -Wtarget=TNS/E and -Wsystype=guardian flags |

| are specified or used by default.

xvi Hewlett-Packard Company 527186-003

About This Manual

SYNOPSIS

Appropriate syntax, including header files to be included and all parameter types. Some header files are required for POSIX.1-compliant applications but are optional for applications conforming to other standards. These header files are noted as "optional except for POSIX.1."

PARAMETERS Descriptions of the parameters listed under the SYNOPSIS heading.

DESCRIPTION For function topics, how the function works, including the conditions or permissions required to use it successfully, the set of values for all parameters, and the effect of the function on the state of processes or files. For file topic reference pages, a description of file contents. For miscellaneous topics, a general description.

EXAMPLES

Compilable C language program excerpts using the function call described in the reference page.

NOTES

Any supplementary information that is peripheral to the actual operation of the function, file, or miscellaneous topic described.

CAUTIONS

Information on possible system damage or data corruption as a result of using the function, file, or miscellaneous topic in a specific way.

RETURN VALUES Indication of successful or unsuccessful completion when the function is invoked.

ERRORS

Error conditions under which the function might fail, and the errno value associated with each condition.

FILES

Files related to the function, file, or miscellaneous topic, except for any header files listed under the SYNOPSIS heading.

RELATED INFORMATION Cross-references to related functions, files, commands, and miscellaneous topics described in other OSS reference pages. This heading does not contain titles of standards, HP manuals, or commercial texts.

STANDARDS CONFORMANCE Summary of features that are fully described under previous headings and are flagged as implementation-defined or HP extensions to XPG4 or XPG4 Version 2 under this heading.

The POSIX standards leave some features to the implementing vendor to define. These features are flagged as implementation-defined. Features that HP has included that are not in the XPG4 specification are flagged as HP extensions to the appropriate XPG4 specification.

Related Documents

Refer to the following manuals for information about OSS library functions, commands and utilities, and guidelines for general usage:

C/C++ Programmer’s Guide

Common Run-Time Environment (CRE) Programmer’s Guide

527186-003 Hewlett-Packard Company xvii

OSS System Calls Reference Manual

eld Manual (TNS/E systems only)

enoft Manual (TNS/E systems only)

H-Series Application Migration Guide

Inspect Manual

ld Manual

Native Inspect Manual (TNS/E systems only)

rld Manual

nld Manual

noft Manual

Open System Services Library Calls Reference Manual

Open System Services Porting Guide

Open System Services Programmer’s Guide

Open System Services Shell and Utilities Reference Manual

Open System Services User’s Guide

Software Internationalization Guide

TCP/IP and TCP/IPv6 Programming Manual

TNS/R Native Application Migration Guide

Programmers working in or with the Guardian environment should refer to the Guardian

Procedure Calls Reference Manual and its related manuals.

Reference Section Numbers

The online documentation for Open System Services is divided into logical sections.

Each logical section has a reference section number.

Some topics in the reference pages have more than one reference page file; a reference section number identifies a specific file. For example, chown has a reference page for the

chown( ) function in section 2 and a reference page for the chown command in section 1.

These are identified as chown(2) and chown(1), respectively.

The reference section number can be used in the man command to select the correct reference page. Refer to the man command reference page either online or in the Open

System Services Shell and Utilities Reference Manual for more information about the

section parameter.

Reference section numbers are included under the RELATED INFORMATION heading and in the heading at the top of every reference page. The following table shows the correspondence between reference section numbers and OSS manuals.

xviii Hewlett-Packard Company 527186-003

About This Manual

(1)

(2)

(3)

(4)

(5)

(6)

(7)

(8)

Content Manual

User commands

System functions

Library functions

File formats and data structures

OSS Shell and Utilities Reference Manual

OSS System Calls Reference Manual

OSS Library Calls Reference Manual

OSS System Calls Reference Manual

(SPT_*( ) functions)

OSS System Calls Reference Manual

OSS Library Calls Reference Manual

OSS Shell and Utilities Reference Manual

Miscellaneous topics and

OSS System Calls Reference Manual

environment variables

OSS Library Calls Reference Manual

OSS Shell and Utilities Reference Manual

Games Not supplied by HP

Special files

OSS System Calls Reference Manual

Administrator commands

OSS Shell and Utilities Reference Manual

Typographic and Keying Conventions

This manual uses the following typographic conventions:

Bold

Bold words or characters represent system elements that you must use literally, such as commands, flags, and pathnames.

Italic

Italic words or characters represent variable values that you must supply.

Constant width

Examples and information that the system displays appear in the constant width typeface.

[ ]

|

Brackets enclose optional items in format and syntax descriptions.

A vertical bar separates items in a list of choices.

...

A horizontal ellipsis indicates that you can repeat the preceding item one or more times. A vertical ellipsis indicates that you can repeat the preceding line one or more times.

In text margins, a vertical bar indicates a line changed since the last revision of the reference page.

527186-003 Hewlett-Packard Company xix

Section 1. System Functions (a - d)

This section contains reference pages for Open System Services (OSS) system function calls with names that begin with a through d. These reference pages reside in the cat2 directory and are sorted alphabetically by U.S. English conventions in this section.

527186-003 Hewlett-Packard Company 1

1

accept(2) OSS System Calls Reference Manual

NAME

accept - Accepts a new connection on a socket

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/socket.h> int accept(

int socket,

struct sockaddr *address,

size_t *address_len

);

PARAMETERS

socket

Specifies the file descriptor for a socket that was created with the socket( ) function, has been bound to an address with the bind( ) function, and has issued a successful call to the listen( ) function.

address

Specifies either a null pointer or a pointer to the sockaddr structure where the address of the peer socket that requested the connection should be returned. The length and format of the address depend on the address family of the socket.

For AF_INET sockets, a pointer to the address structure sockaddr_in must be cast as a struct sockaddr. For AF_INET6 sockets, a pointer to the address structure sockaddr_in6 must be cast as a struct sockaddr. For AF_UNIX sockets, a pointer to the address structure sockaddr_un must be cast as a struct

sockaddr.

address_len

Points to a size_t data item, which, on input, specifies the length of the sockaddr structure pointed to by the address parameter, and, on output, specifies the length of the address returned.

DESCRIPTION

The accept( ) function extracts the first connection on the queue of pending connections, creates a new socket with the same socket type, protocol, and address family as the specified socket, and allocates a new file descriptor for that socket.

When the accept( ) function is called using a value for the address parameter that is null, successful completion of the call returns a socket file descriptor without modifying the value pointed to by the address_len parameter. When the accept( ) function is called using a value for the

address parameter that is not null, a successful call places the address of the peer socket in the

sockaddr structure pointed to by the address parameter, and places the length of the peer socket’s address in the location pointed to by the address_len parameter.

If the length of the socket address is greater than the length of the supplied sockaddr structure, the address is truncated when stored.

If the queue of pending connections is empty of connection requests and the socket’s file descriptor is blocking (O_NONBLOCK is not set), the accept( ) function blocks until a connection is present. If the socket’s file descriptor is marked nonblocking (O_NONBLOCK is set) and the queue of pending connections is empty, the accept( ) function call fails and sets errno to

[EWOULDBLOCK].

1

2 Hewlett-Packard Company 527186-003

System Functions (a - d) accept(2)

NOTES

When a connection is available, a call to the select( ) function indicates that the file descriptor for the original socket is ready for reading.

The accepted socket cannot itself accept more connections. The original socket remains open and can accept more connections.

RETURN VALUES

Upon successful completion, the accept( ) function returns the file descriptor of the accepted socket. If the accept( ) function call fails, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the accept( ) function sets errno to the corresponding value:

[EBADF] The socket parameter is not a valid file descriptor.

[ECONNABORTED]

The connection was aborted.

[ECONNRESET]

One of the following conditions occurred:

The transport-provider process for this socket is no longer available.

The TCP/IP subsystem for this socket is no longer available.

The connection was forcibly closed by the peer socket.

The socket can only be closed.

[EFAULT] A user-supplied memory buffer cannot be accessed or written.

[EINTR]

[EINVAL]

[EMFILE]

The function call was interrupted by a signal that was caught before a valid connection arrived.

The socket is not accepting connections.

No more file descriptors are available for this process.

[ENFILE] The maximum number of file descriptors for this processor are already open.

[ENOBUFS] There was not enough buffer space available to complete the call. A retry at a later time might succeed.

[ENOMEM] Required memory resources were not available. A retry at a later time may succeed.

[ENOTSOCK] The socket parameter does not specify a socket.

[EOPNOTSUPP]

The socket type of the specified socket does not support accepting connections.

[EWOULDBLOCK]

The socket’s file descriptor is marked nonblocking (O_NONBLOCK is set) and no connections are present to be accepted.

527186-003 Hewlett-Packard Company 1

3

accept(2) OSS System Calls Reference Manual

RELATED INFORMATION

Functions: bind(2), connect(2), listen(2), socket(2).

STANDARDS CONFORMANCE

The XPG4 specification allows certain behaviors to be implementer-defined. The following are choices of the HP implementation:

The HP implementation does not return the errno values [EAGAIN], [ENOSR], or

[EPROTO].

The following are HP extensions to the XPG4 specification:

The errno value [ECONNRESET] can be returned when the transport-provider process is unavailable.

1

4 Hewlett-Packard Company 527186-003

System Functions (a - d) access(2)

NAME

access - Determines the accessibility of a file

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <unistd.h> int access(

const char *path,

int access_mode);

PARAMETERS

path

Points to the file pathname. When the path parameter refers to a symbolic link, the access( ) function returns information about the file pointed to by the symbolic link.

Permission to access all components of the path parameter is determined by using a real user ID instead of an effective user ID, and by using a real group ID instead of an effective group ID.

access_mode

Specifies the type of access. The bit pattern contained in the access_mode parameter is constructed by a logical OR of values from the following list:

F_OK

R_OK

W_OK

X_OK

Checks to see whether the file exists.

Checks read permission.

Checks write permission.

Checks execute (search) permission.

DESCRIPTION

The access( ) function checks the accessibility of a file specified by a pathname.

Only access bits are checked. A directory can be indicated as writable by access( ), but an attempt to open it for writing could fail (although files can be created there).

To override the file access control mechanism, a process must have a user ID of the super ID.

Files in the Guardian File System

If the specified pathname resolves to the /G directory itself, the calling process has read and execute access but not write access. The permissions are "r-xr-xr-x".

If the specified pathname resolves to a Guardian process name, the calling process has execute access but not read or write access. The permissions are "--x--x--x".

If the specified pathname resolves to a Guardian disk volume or subvolume, then the calling process has read, write, and execute access. The permissions are "rwxrwxrwx".

If the specified pathname resolves to a regular Guardian disk file, then Guardian standard security and Safeguard file-level protection govern access. Refer to the stat(2) reference page for more information.

527186-003 Hewlett-Packard Company 1

5

access(2) OSS System Calls Reference Manual

Use From the Guardian Environment

The access( ) function is one of a set of functions that have the following effects when the first of them is called from the Guardian environment:

Two Guardian file system file numbers (not necessarily the next two available) are allocated for the root directory and the current working directory. These file numbers cannot be closed by calling the Guardian FILE_CLOSE_ procedure.

The current working directory is assigned from the VOLUME attribute of the Guardian environment =_DEFAULTS DEFINE.

The use of static memory by the process increases slightly.

These effects occur only when the first of the set of functions is called. The effects are not cumulative.

RETURN VALUES

Upon successful completion, the access( ) function returns the value 0 (zero). Otherwise, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the access( ) function sets errno to the corresponding value:

[EACCES] The permission bits of the file mode do not permit the requested access, or search permission is denied on a component of the pathname prefix. The owner of a file has permissions checked with respect to the "owner" read, write, and execute mode bits; members of the file’s group other than the owner have permissions checked with respect to the "group" mode bits; and all others have permissions checked with respect to the "other" mode bits.

The path parameter points outside the process’s allocated address space.

[EFAULT]

[EFSBAD]

[EINTR]

[EINVAL]

[EIO]

The program attempted an operation involving a fileset with a corrupted fileset catalog.

A signal was caught during execution of the function call.

The access_mode parameter contains an invalid bit pattern.

An I/O error occurred during a read from or a write to the fileset.

[ELOOP] Too many symbolic links were encountered in translating the pathname.

[ENAMETOOLONG]

One of the following is too long:

The pathname pointed to by the path parameter

A component of the pathname pointed to by the path parameter

The intermediate result of pathname resolution when a symbolic link is part of the path parameter

The pathconf( ) function can be called to obtain the applicable limits.

1

6 Hewlett-Packard Company 527186-003

System Functions (a - d) access(2)

[ENOENT] One of the following conditions exists:

The specified pathname does not exist.

The specified pathname is an empty string.

The specified pathname cannot be mapped to a valid Guardian filename.

The path parameter specifies a file on a remote HP NonStop node but communication with the remote node has been lost.

[ENOROOT] One of the following conditions exists:

The root fileset of the local node (fileset 0) is not in the STARTED state.

The current root fileset for the specified file is unavailable. The OSS name server for the fileset might have failed.

The specified file is on a remote HP NonStop node and communication with the remote name server has been lost.

[ENOTDIR] A component of the pathname prefix is not a directory.

[ENXIO] The fileset containing the current working directory or the root fileset is not mounted.

[EOSSNOTRUNNING]

The program attempted an operation on an object in the OSS environment while a required system process was not running.

[EROFS] Write access is requested for a file on a read-only fileset.

[ETXTBSY] Write access is requested for a pure procedure (shared text) file that is being executed.

RELATED INFORMATION

Functions: chmod(2), stat(2).

STANDARDS CONFORMANCE

The POSIX standards leave some features to the implementing vendor to define. The following features are affected in the HP implementation:

To override the file access control mechanism, a process must have a user ID of the super

ID.

The error [EINVAL] can be detected.

The following are HP extensions to the XPG4 Version 2 specification:

The errno values [EFAULT], [EFSBAD], [EINTR], [EIO], [ENOROOT], [ENXIO], and

[EOSSNOTRUNNING] can be returned.

527186-003 Hewlett-Packard Company 1

7

bind(2) OSS System Calls Reference Manual

NAME

bind - Binds a name to a socket

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/socket.h> int bind(

int socket,

const struct sockaddr *address,

size_t address_len

);

PARAMETERS

socket

Specifies the file descriptor of the socket to be bound.

address

Points to a sockaddr structure that contains the address to be bound to the socket. The length and format of the address depend on the address family of the socket.

For AF_INET sockets, a pointer to the address structure sockaddr_in must be cast as a struct sockaddr. For AF_INET6 sockets, a pointer to the address structure sockaddr_in6 must be cast as a struct sockaddr. For AF_UNIX sockets, a pointer to the address structure sockaddr_un must be cast as a struct

sockaddr.

address_len

Specifies the length of the sockaddr structure pointed to by the address parameter.

DESCRIPTION

The bind( ) function assigns a name, which consists of an address stored in a sockaddr structure, to an unnamed socket. Sockets created with the socket( ) function are initially unnamed; they are identified only by their address family.

An application program can retrieve the assigned socket name with the getsockname( ) function.

RETURN VALUES

Upon successful completion, the bind( ) function returns the value 0 (zero). Otherwise, the

bind( ) function returns -1 and sets errno to indicate the error.

ERRORS

If any of the following conditions occurs, the bind( ) function sets errno to the corresponding value:

[EACCES] One of the following conditions occurred:

The specified address is protected and the current user does not have permission to bind to it.

The socket is an AF_UNIX socket and either a component of the path prefix denies search permission, or the requested name requires writing in a directory with a mode that denies write permission.

[EADDRINUSE]

The specified address is already in use.

1

8 Hewlett-Packard Company 527186-003

System Functions (a - d) bind(2)

[EADDRNOTAVAIL]

The specified address is not available on this HP NonStop node.

[EAFNOSUPPORT]

The specified address is not a valid address for the address family of the specified socket.

[EBADF] The socket parameter is not a valid file descriptor.

[ECONNRESET]

One of the following conditions occurred:

The transport-provider process for this socket is no longer available.

The TCP/IP subsystem for this socket is no longer available.

The connection was forcibly closed by the peer socket.

The socket can only be closed.

[EDESTADDRREQ]

The address parameter for an AF_UNIX socket is a null pointer.

[EFAULT] A user-supplied memory buffer cannot be accessed.

[EINVAL] One of the following conditions exists:

The socket is already bound to an address.

The socket has been shut down.

The size specified for the address_len parameter is not valid for an address in the address family that is used by this connection.

[EIO]

[ELOOP]

An input or output error occurred for an AF_UNIX socket.

The socket is in the AF_UNIX domain and too many symbolic links were encountered when translating the pathname specified in the sockaddr structure.

[ENAMETOOLONG]

The socket is in the AF_UNIX domain and one of the following conditions exists:

The pathname in the sockaddr structure exceeds PATH_MAX characters.

A component of the pathname in the sockaddr structure exceeds

NAME_MAX characters.

The intermediate result of pathname resolution when a symbolic link is part of the pathname in the sockaddr structure exceeds PATH_MAX characters.

The pathconf( ) function can be called to obtain the applicable limits.

[ENOENT] The socket is in the AF_UNIX domain and one of the following conditions exists:

A component of the pathname specified in the sockaddr structure does not name an existing file.

527186-003 Hewlett-Packard Company 1

9

bind(2) OSS System Calls Reference Manual

The sockaddr structure specifies an empty string as a pathname.

[ENOBUFS] There was not enough buffer space available to complete the call. A retry at a later time might succeed.

[ENOMEM] Required memory resources were not available. A retry at a later time might succeed.

[ENOTDIR] The socket is in the AF_UNIX domain and a component of the pathname specified in the sockaddr structure is not a directory.

[ENOTSOCK] The socket parameter does not refer to a socket.

[EOPNOTSUPP]

The socket type of the specified socket does not support binding to an address.

[EROFS] The socket is in the AF_UNIX domain and the specified name would reside on a read-only fileset.

RELATED INFORMATION

Functions: connect(2), getsockname(2), listen(2), socket(2).

STANDARDS CONFORMANCE

The XPG4 specification allows certain behaviors to be implementer-defined. The following are choices of the HP implementation:

The HP implementation does not return the errno values [EISCONN], [EISDIR],

[ENOSR], or [EPROTO].

The following are HP extensions to the XPG4 specification:

The errno value [ECONNRESET] can be returned when the transport provider process is unavailable.

1

10 Hewlett-Packard Company 527186-003

System Functions (a - d) chdir(2)

NAME

chdir - Changes the current working directory

LIBRARY

G-series native Guardian processes: system library

G-series native OSS processes: system library

H-series native Guardian processes: implicit libraries

H-series OSS processes: implicit libraries

SYNOPSIS

#include <unistd.h> int chdir(

const char *path);

PARAMETERS

path

Points to the pathname of the directory.

DESCRIPTION

The chdir( ) function changes the current working directory to the directory indicated by the path parameter. If the path parameter refers to a symbolic link, the chdir( ) function sets the current directory to the directory pointed to by the symbolic link.

The current working directory is the starting point for searches for pathnames that do not begin with a / (slash). For a directory to become the current working directory, the calling process must have search (execute) access to the directory.

Use on Guardian Objects

Guardian process names are directories; however, they cannot be opened using chdir( ).

Attempts to do so fail and set errno to the value [EPERM].

A call to the chdir( ) function with a path parameter that points to a subprocess in the Guardian file system fails when the process is not of subtype 30. Such a call sets errno to the value

[ENOENT].

A call to the chdir( ) function with a path parameter that points to an empty Guardian disk subvolume (for example, /G/vol/subvol) succeeds.

A call to the chdir( ) function with a path parameter that points to a Guardian subvolume with a reserved name (for example, /G/vol1/zyq00001) fails. Such a call sets errno to the value

[EPERM].

Use From the Guardian Environment

The chdir( ) function is one of a set of functions that have the following effects when the first of them is called from the Guardian environment:

Two Guardian file system file numbers (not necessarily the next two available) are allocated for the root directory and the current working directory. These file numbers cannot be closed by calling the Guardian FILE_CLOSE_ procedure.

The current working directory is assigned from the VOLUME attribute of the Guardian environment =_DEFAULTS DEFINE.

The use of static memory by the process increases slightly.

These effects occur only when the first of the set of functions is called. The effects are not cumulative.

527186-003 Hewlett-Packard Company 1

11

chdir(2) OSS System Calls Reference Manual

RETURN VALUES

Upon successful completion, the chdir( ) function returns the value 0 (zero). Otherwise, the value -1 is returned, and errno is set to indicate the error.

ERRORS

If any of these conditions occurs, the chdir( ) function sets errno to the corresponding value:

[EACCES]

[EFAULT]

[EFSBAD]

[EIO]

The requested current working directory is not accessible because search permission is denied for a component of the pathname.

The path parameter is an invalid address.

The fileset catalog for one of the filesets involved in the operation is corrupt.

A physical input or output error occurred.

[ELOOP] Too many symbolic links were encountered in translating the pathname.

[ENAMETOOLONG]

One of these is too long:

The pathname pointed to by the path parameter

A component of the pathname pointed to by the path parameter

The intermediate result of pathname resolution when a symbolic link is part of the path parameter

The pathconf( ) function can be called to obtain the applicable limits.

[ENOENT] One of these conditions exists:

The named directory does not exist.

The specified pathname is an empty string.

The specified pathname cannot be mapped to a valid Guardian filename.

The specified pathname points to the name of a Guardian process that is not of subtype 30.

The path parameter names a symbolic link, but the directory to which it refers does not exist.

The path parameter specifies a file on a remote HP NonStop node, but communication with the remote node has been lost.

[ENOROOT] One of these conditions exists:

The root fileset of the local node (fileset 0) is not in the STARTED state.

The current root fileset for the specified file is unavailable. The OSS name server for the fileset might have failed.

The specified file is on a remote HP NonStop node, and communication with the remote name server has been lost.

1

12 Hewlett-Packard Company 527186-003

System Functions (a - d) chdir(2)

[ENOTDIR] A component of the pathname is not a directory.

[ENXIO] The fileset containing the client’s current working directory or root directory is not mounted.

[EOSSNOTRUNNING]

The program attempted an operation on an object in the OSS environment while a required system process was not running.

[EPERM] The program attempted an operation on a Guardian process or attempted to access a Guardian ZYQ subvolume.

For all other error conditions, errno is set to the appropriate Guardian file-system error number.

See the Guardian Procedure Errors and Messages Manual for more information about a specific

Guardian file-system error.

RELATED INFORMATION

Commands: cd(1).

Functions: chroot(2).

STANDARDS CONFORMANCE

The following are HP extensions to the XPG4 Version 2 specification:

The errno values [EFAULT], [EFSBAD], [EIO], [ENOROOT], [ENXIO],

[EOSSNOTRUNNING], and [EPERM] can be returned.

527186-003 Hewlett-Packard Company 1

13

chmod(2) OSS System Calls Reference Manual

NAME

chmod - Changes file access permissions

LIBRARY

G-series native Guardian processes: system library

G-series native OSS processes: system library

H-series native Guardian processes: implicit libraries

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/types.h>

/* optional except for POSIX.1 */

#include <sys/stat.h> int chmod(

const char *path,

mode_t mode);

PARAMETERS

path mode

Specifies the full pathname of the file. If the path parameter refers to a symbolic link, the chmod( ) function changes access permissions on the file specified by the symbolic link.

Specifies the bit pattern that determines the access permissions.

DESCRIPTION

The chmod( ) function sets the access permissions of the file specified by the path parameter according to the bit pattern specified by the mode parameter.

To change file-access permissions, either the process must have appropriate privileges or its effective user ID must be the same as the user ID of the file owner.

If the S_ISVTX bit is on for a directory, only processes with an effective user ID equal to the user ID of the file’s owner or the directory’s owner, or a process with appropriate privileges, can remove files from the directory.

A call to the chmod( ) function has no effect on the file descriptor for a file that is open at the time of the call. However, new openers of the file will be authorized by using the new access permissions that were specified in the call.

The mode parameter is constructed by logically ORing one or more of these symbols, which are defined in the sys/stat.h header file:

S_ISUID

S_ISGID

S_ISVTX

S_IRWXU

S_IRUSR

Sets the process’s effective user ID to the user ID of the file’s owner on execution.

Sets the process’s effective group ID to the group ID of the file’s group on execution.

For a directory, permits modification to the directory only if the effective user ID of the process matches that of the file being accessed.

Permits the file’s owner to read, write, and execute the file (or to search the directory).

Permits the file’s owner to read the file.

1

14 Hewlett-Packard Company 527186-003

System Functions (a - d) chmod(2)

S_IWUSR

Permits the file’s owner to write to the file.

S_IXUSR

Permits the file’s owner to execute the file (or to search the directory).

S_IRWXG

Permits the file’s group to read, write, and execute the file (or to search the directory).

S_IRGRP

S_IWGRP

Permits the file’s group to read the file.

Permits the file’s group to write to the file.

S_IXGRP

Permits the file’s group to execute the file (or to search the directory).

S_IRWXO

Permits others to read, write, and execute the file (or to search the directory).

S_IROTH

Permits others to read the file.

S_IWOTH

Permits others to write to the file.

S_IXOTH

Permits others to execute the file (or to search the directory).

S_NONSTOP For a regular file, setting this flag results in:

Disabling file system caching.

Returning control to a calling process only after the backup disk process has received checkpoint data for a write operation.

S_TRUST

Establishes that the file does not contain code for an uncooperative process or code to examine or modify I/O buffers. This flag suppresses operating system protection of the buffers when the memory segment containing the buffers is not shared. This flag applies only to loadfiles for a TNS/E native process and can be set only by a user with appropriate privileges (the super ID).

S_TRUSTSHARED

Establishes that the file does not contain code for an uncooperative process or code to examine or modify I/O buffers. This flag suppresses operating system protection of the buffers regardless of whether the memory segment containing the buffers is shared. This flag applies only to loadfiles for a TNS/E native process and can be set only by a user with appropriate privileges (the super ID).

The S_ISUID bit of the file is not changed by the call if the file specified by the path parameter resides on an HP NonStop node where the calling process is not logged in.

The S_ISGID bit of the file is cleared if all of these conditions are true:

The named file is a regular file.

The process does not have appropriate privileges.

The file’s group ID does not match the effective group ID of the process or one of the IDs of the process’s group list.

Upon successful completion, the chmod( ) function marks the st_ctime field of the file for update.

527186-003 Hewlett-Packard Company 1

15

chmod(2) OSS System Calls Reference Manual

Use on Guardian Objects

Attempting to set the access permissions on a Guardian file (that is, a file in the /G file system) fails with errno set to [EINVAL].

Use From the Guardian Environment

The chmod( ) function is one of a set of functions that have these effects when the first of them is called from the Guardian environment:

Two Guardian file system file numbers (not necessarily the next two available) are allocated for the root directory and the current working directory. These file numbers cannot be closed by calling the Guardian FILE_CLOSE_ procedure.

The current working directory is assigned from the VOLUME attribute of the Guardian environment =_DEFAULTS DEFINE.

The use of static memory by the process increases slightly.

These effects occur only when the first of the set of functions is called. The effects are not cumulative.

RETURN VALUES

Upon successful completion, the chmod( ) function returns the value 0 (zero). Otherwise, the value -1 is returned, and errno is set to indicate the error.

ERRORS

If any of these conditions occurs, the chmod( ) function sets errno to the corresponding value:

[EACCES]

[EFAULT]

[EFSBAD]

[EINVAL]

Search permission is denied for a component of the path parameter.

The path parameter points to a location outside of the allocated address space of the process.

The fileset catalog for one of the filesets involved in the operation is corrupt.

One of these conditions exists:

The value of the mode parameter is invalid.

An attempt was made to set access permissions on a Guardian file (that is, a file in the /G file system).

[EIO] An input or output error occurred. The device holding the file might be in the down state, or both processors that provide access to the device might have failed.

Too many symbolic links were encountered in translating the path parameter.

[ELOOP]

[ENAMETOOLONG]

One of these is too long:

The pathname pointed to by the path parameter

A component of the pathname pointed to by the path parameter

The intermediate result of pathname resolution when a symbolic link is part of the path parameter

The pathconf( ) function can be called to obtain the applicable limits.

1

16 Hewlett-Packard Company 527186-003

System Functions (a - d) chmod(2)

[ENOENT] One of these conditions exists:

The named file does not exist, or the specified name is an empty string.

The path parameter specifies a file on a remote HP NonStop node, but communication with the remote node has been lost.

[ENOROOT] One of these conditions exists:

The root fileset of the local node (fileset 0) is not in the STARTED state.

The current root fileset for the specified file is unavailable. The OSS name server for the fileset might have failed.

The specified file is on a remote HP NonStop node, and communication with the remote name server has been lost.

[ENOTDIR] A component, other than the last part, of the path parameter is not a directory.

[ENXIO] The fileset containing the client’s current working directory or root directory is not mounted.

[EOSSNOTRUNNING]

The program attempted an operation on an object in the OSS environment while a required system process was not running.

[EPERM]

[EROFS]

The effective user ID does not match the user ID of the owner of the file, or the owner does not have appropriate privileges.

The named file resides on a read-only fileset.

For all other error conditions, errno is set to the appropriate Guardian file-system error number.

See the Guardian Procedure Errors and Messages Manual for more information about a specific

Guardian file-system error.

RELATED INFORMATION

Commands: chmod(1).

Functions: chown(2), fcntl(2), getgroups(2), mknod(2), open(2), read(2), write(2).

STANDARDS CONFORMANCE

The POSIX standards leave some features to the implementing vendor to define. These features are affected in the HP implementation:

To change file-access permissions, either the process must have the same effective user

ID as the owner of the file or the process must have an effective user ID of the super ID.

A call to the chmod( ) function has no effect on the file descriptor for a file that is open at the time of the call. However, new openers of the file are authenticated by using the new access permissions that were specified in the call.

HP extensions to the XPG4 Version 2 specification are:

The errno values [EFAULT], [EFSBAD], [EINVAL], [ENOROOT], [ENXIO], and

[EOSSNOTRUNNING] can be returned.

The S_NONSTOP flag is supported for regular files.

527186-003 Hewlett-Packard Company 1

17

chown(2) OSS System Calls Reference Manual

NAME

chown - Changes the owner and group IDs of a file

LIBRARY

G-series native Guardian processes: system library

G-series native OSS processes: system library

H-series native Guardian processes: implicit libraries

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/types.h>

/* optional except for POSIX.1 */

#include <unistd.h> int chown(

const char *path,

uid_t owner,

gid_t group);

PARAMETERS

path owner group

Specifies the name of the file whose owner ID, group ID, or both are to be changed. If the final component of the path parameter names a symbolic link, the link is traversed, and pathname resolution continues.

When the path parameter refers to a symbolic link, the chown( ) function changes the ownership of the file pointed to by the symbolic link.

Specifies a numeric value representing the owner ID.

Specifies a numeric value representing the group ID.

DESCRIPTION

The chown( ) function changes the owner and group of a file.

A process can change the value of the owner ID of an OSS file only if the effective user ID of the process gives the process appropriate privileges. A process can change the value of the file group ID if the effective user ID of the process matches the owner ID of the file or the process has appropriate privileges. A process without appropriate privileges can change the group ID of a file only to the value of its effective group ID or to a value in its group list. However, if the

chown( ) function is successfully invoked on a file, the S_ISGID and S_ISUID bits of the

st_mode field of the stat structure are cleared unless the user has appropriate privileges.

The _POSIX_CHOWN_RESTRICTED feature is enforced for a regular file in the Open System Services file system. Only processes with appropriate privileges can change owner IDs.

If the owner or group parameter is specified as -1 cast to the type of uid_t or gid_t, respectively, the corresponding ID of the file is unchanged. To change only one attribute, specify the other as

-1.

Upon successful completion, the chown( ) function marks the st_ctime field of the file for update.

Use on Guardian Objects

The chown( ) function can be used on Guardian disk files (that is, disk files in the /G file system).

Attempts to change the ownership of other types of Guardian files fail and set errno to [EIN-

VAL].

For Guardian disk files, Guardian security is used, and any user can ass file ownership to any other user. A value other than -1 must be specified for the owner parameter (that is, an owner ID must be specified). However, changing the owner ID also changes the group ID to the Guardian group ID of the new owner (that is, bits <16:23> of the new access ID). The chown( ) function cannot be used to set the group ID for a Guardian file except as a result of changing the owner

ID.

1

18 Hewlett-Packard Company 527186-003

System Functions (a - d) chown(2)

The _POSIX_CHOWN_RESTRICTED feature is ignored for files in the Guardian file system

(that is, for files in /G).

Use From the Guardian Environment

The chown( ) function is one of a set of functions that have these effects when the first of them is called from the Guardian environment:

Two Guardian file system file numbers (not necessarily the next two available) are allocated for the root directory and the current working directory. These file numbers cannot be closed by calling the Guardian FILE_CLOSE_ procedure.

The current working directory is assigned from the VOLUME attribute of the Guardian environment =_DEFAULTS DEFINE.

The use of static memory by the process increases slightly.

These effects occur only when the first of the set of functions is called. The effects are not cumulative.

RETURN VALUES

Upon successful completion, the chown( ) function returns the value 0 (zero). Otherwise, the value -1 is returned, the owner and group of the file remain unchanged, and errno is set to indicate the error.

ERRORS

If these conditions occurs, the chown( ) function sets errno to the corresponding value:

[EACCES]

[EFAULT]

[EFSBAD]

[EINVAL]

Search permission is denied on a component of the path parameter.

The path parameter is an invalid address.

The fileset catalog for one of the filesets involved in the operation is corrupt.

[EIO]

The owner or group parameter is out of range.

An attempt was made to change ownership of a Guardian file that is not a disk file.

An input or output error occurred. The device holding the file might be in the down state, or both processors that provide access to the device might have failed.

[ELOOP] Too many links were encountered in translating the path parameter.

[ENAMETOOLONG]

One of these is too long:

The pathname pointed to by the path parameter

A component of the pathname pointed to by the path parameter

The intermediate result of pathname resolution when a symbolic link is part of the path parameter

The pathconf( ) function can be called to obtain the applicable limits.

[ENOENT] One of these is true:

The path parameter does not exist.

527186-003 Hewlett-Packard Company 1

19

chown(2) OSS System Calls Reference Manual

The path parameter is an empty string.

The path parameter specifies a file in the Guardian file system (in /G) but cannot be mapped to a valid Guardian filename.

The path parameter names a symbolic link, but the file to which it refers does not exist.

The path parameter specifies a file on a remote HP NonStop node, but communication with the remote node has been lost.

[ENOROOT] One of these conditions exists:

The root fileset of the local node (fileset 0) is not in the STARTED state.

The current root fileset for the specified file is unavailable. The OSS name server for the fileset might have failed.

The specified file is on a remote HP NonStop node, and communication with the remote name server has been lost.

[ENOTDIR] A component of path is not a directory.

[ENXIO] The fileset containing the client’s current working directory or root directory is not mounted.

[EOSSNOTRUNNING]

The program attempted an operation on an object in the OSS environment while a required system process was not running.

[EPERM]

[EROFS]

The calling process does not have appropriate privileges.

The named file resides on a read-only fileset.

For all other error conditions, errno is set to the appropriate Guardian file-system error number.

See the Guardian Procedure Errors and Messages Manual for more information about a specific

Guardian file-system error.

RELATED INFORMATION

Commands: chgrp(1), chown(1).

Functions: chmod(2).

STANDARDS CONFORMANCE

The POSIX standards leave some features to the implementing vendor to define. These features are affected in the HP implementation:

A process can change the value of the owner ID of a file only if the effective user ID of the process gives the process appropriate privileges.

Upon successful completion, the set-user-ID attribute (the S_ISUID bit) and the setgroup-ID attribute (the S_ISGID bit) of the file are always cleared.

The error [EINVAL] can be detected.

1

20 Hewlett-Packard Company 527186-003

System Functions (a - d)

HP extensions to the XPG4 Version 2 specification are:

The errno values [EFAULT], [EFSBAD], [EIO], [ENOROOT], [ENXIO], and

[EOSSNOTRUNNING] can be returned.

chown(2)

527186-003 Hewlett-Packard Company 1

21

chroot(2) OSS System Calls Reference Manual

NAME

chroot - Changes the effective root directory

LIBRARY

G-series native Guardian processes: system library

G-series native OSS processes: system library

H-series native Guardian processes: implicit libraries

H-series OSS processes: implicit libraries

SYNOPSIS

#include <unistd.h> int chroot(

const char *path);

PARAMETERS

path

Specifies the new effective root directory. If the path parameter refers to a symbolic link, the chroot( ) function sets the effective root directory to the directory pointed to by the symbolic link.

The path parameter cannot specify /E, and the current working directory of the calling process cannot be a directory in /E. If either condition is not met, the call fails and errno is set to the value [EINVAL].

DESCRIPTION

The chroot( ) function causes the directory named by the path parameter to become the effective root directory. The effective root directory is the starting point when searching for a file with an absolute pathname.

The current working directory is not changed by a call to the chroot( ) function. However, if an absolute pathname is specified in a subsequent call to the chdir( ) function, that pathname is resolved using the effective root directory.

The calling process must have appropriate privileges in order to change the effective root directory. The calling process must also have search access to the new effective root directory.

The . . (dot-dot) entry in the effective root directory is interpreted to mean the effective root directory itself. Thus, . . (dot-dot) cannot be used to access files outside the subtree rooted at the effective root directory.

Use on Guardian Objects

The path parameter can specify /G or any volume or subvolume in /G.

Guardian process names are directories; however, they cannot be opened using chroot( ).

Attempts to do so fail and set errno to the value [EPERM].

A call to the chroot( ) function with a path parameter that points to a subprocess in the Guardian file system fails when the process is not of subtype 30. Such a call sets errno to the value

[ENOENT].

A call to the chroot( ) function with a path parameter that points to an empty Guardian disk subvolume (for example, /G/vol/subvol) succeeds.

A call to the chroot( ) function with a path parameter that points to a Guardian subvolume with a reserved name (for example, /G/vol1/zyq00001) fails. Such a call sets errno to the value

[EPERM].

1

22 Hewlett-Packard Company 527186-003

System Functions (a - d) chroot(2)

Use From the Guardian Environment

The chroot( ) function is one of a set of functions that have the following effects when the first of them is called from the Guardian environment:

Two Guardian file-system file numbers (not necessarily the next two available) are allocated for the root directory and the current working directory. These file numbers cannot be closed by calling the Guardian FILE_CLOSE_ procedure.

The current working directory is assigned from the VOLUME attribute of the Guardian environment =_DEFAULTS DEFINE.

The use of static memory by the process increases slightly.

These effects occur only when the first of the set of functions is called. The effects are not cumulative.

NOTES

Use of this function can make an application difficult to port to another system.

If the effective root directory is not / (the local node root directory), all files in /E become unavailable to the program when the call is completed.

RETURN VALUES

Upon successful completion, the value 0 (zero) is returned. Otherwise, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the effective root directory remains unchanged and the

chroot( ) function sets errno to the corresponding value:

[EACCES]

[EFAULT]

[EFSBAD]

[EINVAL]

Search permission is denied for any component of the pathname.

The path parameter points outside the process’s allocated address space.

The fileset catalog for one of the filesets involved in the operation is corrupt.

One of the following conditions exists:

The path parameter specifies a Guardian process in /G.

The path parameter specifies a file in /E.

The current working directory of the calling process is in /E.

[ELOOP] More than MAXSYMLINKS symbolic links were encountered while resolving

path.

[ENAMETOOLONG]

One of the following is too long:

The pathname pointed to by the path parameter

A component of the pathname pointed to by the path parameter

The intermediate result of pathname resolution when a symbolic link is part of the path parameter

The pathconf( ) function can be called to obtain the applicable limits.

527186-003 Hewlett-Packard Company 1

23

chroot(2) OSS System Calls Reference Manual

[ENOENT] One of the following conditions exists:

The named directory does not exist.

The specified pathname is an empty string.

The specified pathname cannot be mapped to a valid Guardian filename.

[ENOROOT] The root fileset (fileset 0) is not in the STARTED state.

[ENOTDIR] A component of the specified pathname is not a directory.

[ENXIO] The fileset containing the client’s working directory or effective root directory is not mounted.

[EOSSNOTRUNNING]

The program attempted an operation on an object in the OSS environment while a required system process was not running.

[EPERM] One of the following conditions exists:

The path parameter specifies a subvolume in /G with a reserved name

(for example, /G/volume/ZYQ00000).

The path parameter specifies a process name in /G (for example,

/G/ztnt).

The path parameter specifies an invalid subvolume name in /G.

The process does not have appropriate privileges.

RELATED INFORMATION

Commands: cd(1).

Functions: chdir(2).

STANDARDS CONFORMANCE

The following are HP extensions to the XPG4 Version 2 specification:

The errno values [EFAULT], [EFSBAD], [EINVAL], [ENOROOT], [ENXIO], and

[EOSSNOTRUNNING] can be returned.

1

24 Hewlett-Packard Company 527186-003

System Functions (a - d) close(2)

NAME

close - Closes a file descriptor

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <unistd.h> int close(

int filedes);

PARAMETERS

filedes

Specifies an open file descriptor obtained from a successful call to the accept( ),

creat( ), dup( ), dup2( ), fcntl( ), open( ), pipe( ), socket( ), or socketpair( ) function.

DESCRIPTION

The close( ) function closes the file descriptor specified by the filedes parameter.

All regions of the file associated with the filedes parameter that this process has previously locked with the fcntl( ) function are unlocked. This occurs even if the process still has the file open by another file descriptor.

When the last file descriptor associated with an open file descriptor is closed:

The open file descriptor is freed.

The last modification time for the file is updated.

All locks created by fcntl( ) for the file are released.

If the link count of the file is 0 (zero), the space occupied by the file is freed, and the file is no longer accessible.

If the file is a socket, the socket is destroyed.

If the file is a pipe or FIFO, any data remaining in the pipe or FIFO is discarded.

RETURN VALUES

Upon successful completion, the value 0 (zero) is returned. Otherwise, the value -1 is returned, and errno is set to indicate the error.

ERRORS

If any of these conditions occur, the close( ) function sets errno to the corresponding value:

[EBADF] The filedes parameter is not a valid open file descriptor.

[EIO] An input or output error occurred. The device that the file is stored on might be in the down state, or both processors that provide access to the device might have failed.

[EISGUARDIAN]

The value used for the filedes parameter is appropriate only in the Guardian environment.

For all other error conditions, errno is set to the appropriate Guardian filesystem error number. See the Guardian Procedure Errors and Messages

Manual for more information about a specific Guardian file-system error.

527186-003 Hewlett-Packard Company 1

25

close(2) OSS System Calls Reference Manual

RELATED INFORMATION

Functions: exec(2), fcntl(2), getsockopt(2), open(2), pipe(2), setsockopt(2), socket(2),

tdm_execve(2), tdm_execvep(2).

Files: signal(4).

STANDARDS CONFORMANCE

This function does not return the errno value [EINTR].

For an AF_INET or AF_INET6 socket, even if all these are true:

The socket is connection-oriented.

The SO_LINGER option is enabled for the socket.

The socket has untransmitted data.

the close( ) function does not block. The system attempts to deliver unsent data after the close( ) function is called, although that action can be disabled. See the setsockopt(2) reference page for additional information.

HP extensions to the XPG4 Version 2 specification are:

The close( ) function can return the errno value [EISGUARDIAN].

1

26 Hewlett-Packard Company 527186-003

System Functions (a - d)

527186-003 Hewlett-Packard Company

connect(2)

NAME

connect - Connects a socket

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/socket.h> int connect(

int socket,

const struct sockaddr *address,

size_t address_len

);

PARAMETERS

socket

Specifies the file descriptor for the socket.

address

Points to a sockaddr structure that contains the address of the peer socket. The length and format of the address depend on the address family of the socket.

For AF_INET sockets, a pointer to the address structure sockaddr_in must be cast as a struct sockaddr. For AF_INET6 sockets, a pointer to the address structure sockaddr_in6 must be cast as a struct sockaddr. For AF_UNIX sockets, a pointer to the address structure sockaddr_un must be cast as a struct

sockaddr.

address_len

Specifies the length of the sockaddr structure pointed to by the address parameter.

DESCRIPTION

The connect( ) function requests that a connection be made on a socket.

The connect( ) function performs a different action for each of the following types of initiating sockets:

If the initiating socket is not connection-oriented (has the type SOCK_DGRAM), then the connect( ) function sets the peer address but no connection is made. The peer address identifies the socket where all datagrams are sent by subsequent calls to the

send( ) function, and limits the remote sender for subsequent recv( ) function calls.

Datagram sockets can use the connect( ) function multiple times to communicate with different peers.

If the socket is a datagram socket and address is a null address for the protocol, the address for the peer socket is reset.

If the initiating socket is connection-oriented (has the type SOCK_STREAM), then the

connect( ) function attempts to make a connection to the socket specified by the address parameter. Sockets of type SOCK_STREAM can successfully connect only once.

When a connection cannot be created immediately and O_NONBLOCK is not set for the file descriptor of the socket, the connect( ) call blocks until one of the following occurs:

A connection is established

A timeout occurs

A signal is caught

1

27

connect(2) OSS System Calls Reference Manual

If timeout occurs, the connect( ) call fails and errno is set to [ETIMEDOUT]; the connection is aborted.

If a connect( ) call is interrupted by a signal that is caught while the call is blocked waiting to establish a connection, the connect( ) call fails and sets errno to [EINTR]; the connection is not aborted and is later established asynchronously.

When a connection cannot be created immediately and O_NONBLOCK is set for the file descriptor of the socket, the connect( ) call fails and sets errno to [EINPROGRESS]; the connection is not aborted and is later established asynchronously. Subsequent calls to the connect( ) function for the same socket before the connection is completed will fail and set errno to [EAL-

READY].

NOTES

When an asynchronous connection is complete, a call to the select( ) function indicates that the file descriptor for the socket is ready for writing.

RETURN VALUES

Upon successful completion, the connect( ) function returns the value 0 (zero). Otherwise, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the connect( ) function sets errno to the corresponding value:

[EACCES] The socket is in the AF_UNIX domain and either search permission is denied for a component of the pathname in the sockaddr structure, or write access to the specified socket is denied.

[EADDRINUSE]

An attempt was made to establish a connection using addresses that are already in use.

[EADDRNOTAVAIL]

The specified address is not available from this HP NonStop node.

[EAFNOSUPPORT]

Addresses in the specified address family cannot be used with this socket.

[EALREADY] A connection request is already in progress for the specified socket.

[EBADF] The socket parameter is not a valid file descriptor.

[ECONNREFUSED]

The specified address is not listening for connections or rejected the attempt to connect.

[ECONNRESET]

One of the following conditions occurred:

The transport-provider process for this socket is no longer available.

The TCP/IP subsystem for this socket is no longer available.

The connection was forcibly closed by the peer socket.

The socket can only be closed.

1

28 Hewlett-Packard Company 527186-003

System Functions (a - d) connect(2)

[EFAULT] A user-supplied memory buffer cannot be accessed.

[EHOSTUNREACH]

The destination host cannot be reached.

[EINPROGRESS]

The socket is marked nonblocking (O_NONBLOCK is set) and the requested connection is not yet completed. The connection will be completed asynchronously.

[EINTR]

[EINVAL]

The attempt to connect was interrupted by delivery of a signal. The connection will be completed asynchronously.

One of the following conditions exists:

The size specified for the address_len parameter is not valid for an address in the address family that is used by this connection.

The sockaddr structure contains an invalid address family.

[EIO] The socket is in the AF_UNIX domain and an I/O error occurred during a read or write to the file system.

[EISCONN] The specified socket is connection-oriented and is already connected.

[ELOOP] The socket is in the AF_UNIX domain and too many symbolic links were encountered in translating the pathname in the sockaddr structure.

[ENAMETOOLONG]

The socket is in the AF_UNIX domain and one of the following conditions exists:

The pathname in the sockaddr structure exceeds PATH_MAX characters.

A component of the pathname in the sockaddr structure exceeds

NAME_MAX characters.

The intermediate result of pathname resolution when a symbolic link is part of the pathname in the sockaddr structure exceeds PATH_MAX characters.

The pathconf( ) function can be called to obtain the applicable limits.

[ENETDOWN]

The local interface used to reach the destination is down.

[ENETUNREACH]

No route to the network or host is present.

[ENOBUFS] There was not enough buffer space available to complete the call. A retry at a later time may succeed.

[ENOENT] The socket is in the AF_UNIX domain and one of the following conditions exists:

A component of the pathname specified in the sockaddr structure does not name an existing file.

527186-003 Hewlett-Packard Company 1

29

connect(2) OSS System Calls Reference Manual

The sockaddr structure specifies an empty string as a pathname.

[ENOMEM] Required memory resources were not available. A retry at a later time might succeed.

[ENOTDIR] The socket is in the AF_UNIX domain and a component of the pathname specified in the sockaddr structure is not a directory.

[ENOTSOCK] The socket parameter does not refer to a socket.

[EPROTOTYPE]

The specified address has a different type than that of the socket bound to the specified peer address.

[ETIMEDOUT]

The attempt to connect timed out during connection establishment.

RELATED INFORMATION

Functions: accept(2), bind(2), getsockname(2), select(2), send(2), sendmsg(2), sendto(2),

socket(2).

STANDARDS CONFORMANCE

The XPG4 specification allows certain behavior to be implementer-defined. The following are choices of the HP implementation:

The HP implementation does not return the errno values [ENOSR] or [EOPNOTSUPP].

The following are HP extensions to the XPG4 specification:

The errno value [ECONNRESET] can be returned when the transport-provider process is unavailable.

1

30 Hewlett-Packard Company 527186-003

System Functions (a - d) creat(2)

NAME

creat - Creates a regular file in the OSS environment or rewrites an existing file

LIBRARY

G-series native Guardian processes: system library

G-series native OSS processes: system library

H-series native Guardian processes: implicit libraries

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/types.h>

/* optional except for POSIX.1 */

#include <sys/stat.h>

#include <fcntl.h>

/* optional except for POSIX.1 */

int creat(

const char *path,

mode_t mode);

PARAMETERS

path mode

Points to the pathname of the file to be created or opened for writing.

The files /lost+found, /dev, /dev/tty, and /dev/null cannot be specified for this parameter. Attempts to create these files cause the function call to fail with

errno set to [EINVAL].

If the path parameter refers to a symbolic link, the creat( ) function opens the file pointed to by the symbolic link.

Specifies the read, write, and execute permissions of the file and the file type flags for the file.

This parameter is required if the file does not exist. If the file already exists, this parameter must be specified and must have a valid value but has no effect.

The permission bits are set according to the value of this parameter modified by the process’s file creation mask (see the umask(2) reference page). The value of this parameter is constructed by logically ORing flags that are defined in the

sys/stat.h header file.

The file type flags are described in DESCRIPTION.

DESCRIPTION

The creat( ) function establishes a connection between the file indicated by the path parameter and the returned file descriptor. The opened file descriptor is used by subsequent I/O function calls, such as read( ) and write( ), to access that file.

The returned file descriptor is the lowest-numbered file descriptor not previously open for that process. A corresponding Guardian environment file number is also assigned.

The file offset, marking the current position within the file, is set to the beginning of the file. The new file descriptor is set to remain open across the processing of any of the exec or tdm_exec set of functions. (See the fcntl(2) reference page.)

A call to the creat( ) function is equivalent to this call:

open( path, O_WRONLY | O_CREAT | O_TRUNC, mode );

The creat( ) function cannot be used to create a FIFO special file. Use the mkfifo( ) function instead.

If the file does not exist, a regular file is created with these characteristics:

527186-003 Hewlett-Packard Company 1

31

creat(2) OSS System Calls Reference Manual

The owner ID of the file is set to the effective user ID of the process.

The group ID of the file is determined by the value of the S_ISGID flag in the parent directory. If S_ISGID is set, then the group ID of the file is set to the group ID of the parent directory; otherwise, the group ID of the file is set to the effective group ID of the calling process. If the file is a Guardian file (that is, in the /G file system), the group ID is set to that of the primary group of the effective user ID.

The file permission and attribute bits are set to the value of the mode parameter, modified as listed:

— All bits set in the process file mode creation mask are cleared.

— The set user ID attribute (S_ISUID bit) is cleared.

— The set group ID attribute (S_ISGID bit) is cleared.

If bits other than the file permission and appropriate file-type flags are set in the mode parameter, errno is set to [EINVAL].

If the file exists and is a regular file that is successfully opened, then:

The length of the file is truncated to 0 (zero).

The owner and group of the file are unchanged.

The set user ID attribute of the file mode is cleared.

The open fails if any of these conditions are true:

The file supports enforced record locks, and another process has locked a portion of the file.

The file does not allow write access.

A program can request some control over when updates should be made permanent for a regular file opened for write access.

File Type Flags

The file type flags that can be logically ORed into the value specified in the mode parameter are:

S_IFREG

Regular file in the OSS file system or in /G, the Guardian file system.

S_ISVTX

Sticky bit; used only for directories (cannot be used for files in /G, the Guardian file system).

S_NONSTOP Regular file in the OSS file system protected by disk process checkpointing.

(Files in /G cannot have this flag set.)

When set, this flag indicates that return from a write operation does not occur until both the primary and backup disk processes have the data (thereby protecting the data against a single point of failure).

OSS file-system data caching is disabled for write operations on files for which this flag is set. Performance is slower than when caching is used, but data integrity protection increases. Performance is faster than when the O_SYNC flag in the oflag parameter of the open( ) function is used, but data integrity protection is less than that provided by O_SYNC use.

1

32 Hewlett-Packard Company 527186-003

System Functions (a - d) creat(2)

Opening Guardian Files

If the file is a Guardian file (that is, a file in the /G file system), these rules apply:

The file can be opened only if it is one of these:

— An odd, unstructured Enscribe file. In this case, it is opened as a regular file with a primary and secondary extent size that is a multiple of 2. If the extent size is odd, the open fails.

If the unstructured buffer size was not 4096, a successful open makes the buffer size 4096 (as if the Guardian procedure SETMODE was called for mode 93 with a parameter value of 4096).

— An EDIT file (file code 101). In this case, it is opened as a regular file for readonly access.

— A tty simulation process.

An attempt to open any file (or device) of any other type fails, and errno is set to the value of [EINVAL]. An attempt to open a volume, subvolume, or process (/G/vol,

/G/vol/subvol, or /G/process, respectively) fails, and errno is set to the value of [EIS-

DIR].

An attempt to open a subvolume with a reserved name beginning with "ZYQ" (for example, /G/vol2/zyq00004) fails, and errno is set to the value of [EACCES].

An attempt to open a file within a subvolume with a reserved name beginning with

"ZYQ" (for example, /G/vol2/zyq00004/z000002x) fails, and errno is set to the value of

[EACCES].

If the file is not an EDIT file (that is, the file code is not 101), it is opened in shared exclusion mode.

If the file is an EDIT file and read-only access is specified, the file is opened in protected exclusion mode in the Guardian environment.

If the file is an EDIT file and write access is specified, the call fails, and errno is set to the value [EINVAL].

The maximum number of opens is reported by the sysconf( ) function as the upper limit of opens per process. The actual limit depends on other factors, such as the size of the process file segment (PFS) and the number of existing opens on directories or on files in the Guardian environment.

If the open causes file creation, odd unstructured and file code 180 attributes are assumed.

If the open causes file creation, the file is given access permissions compatible with the standard security permissions for the Guardian creator access ID (CAID) of the calling process.

During creat( ) function processing, all access permissions are checked. This includes Guardian environment checks by Guardian standard security mechanisms (and by the Safeguard product) for Guardian disk file and process access.

527186-003 Hewlett-Packard Company 1

33

creat(2) OSS System Calls Reference Manual

Use From the Guardian Environment

A call to the creat( ) function in the Guardian environment requires an OSS pathname and returns an OSS file-system file descriptor, regardless of the file system containing the file.

The creat( ) function belongs to a set of functions that have these effects when the first of them is called from the Guardian environment:

Two Guardian file-system file numbers (not necessarily the next two available) are allocated for the root directory and the current working directory. These file numbers cannot be closed by calling the Guardian FILE_CLOSE_ procedure.

The current working directory is assigned from the VOLUME attribute of the Guardian environment =_DEFAULTS DEFINE.

The use of static memory by the process increases slightly.

These effects occur only when the first of the set of functions is called. The effects are not cumulative.

RETURN VALUES

Upon successful completion, the creat( ) function returns the file descriptor, a nonnegative integer. Otherwise, the value -1 is returned, and errno is set to indicate the error.

ERRORS

If any of these conditions occurs, the function sets errno to the corresponding value:

[EACCES] One of these conditions exists:

Search permission is denied on a component of the pathname prefix.

The file does not exist, and write permission is denied for the parent directory.

The process attempted to open a Guardian subvolume with a reserved name beginning with "ZYQ" or a file within such a subvolume.

The process attempted to open a static Telserv window that is not yet connected.

[EFAULT] The path parameter is an invalid address.

[EFILEBAD] One of these conditions exists:

The function attempted to open a Guardian EDIT file, but the structure of the file is bad.

The function attempted to open a Guardian EDIT file, but the corrupted flag is set in the file label.

[EFSBAD] The fileset catalog for one of the filesets involved in the operation is corrupt.

[EGUARDIANOPEN]

The function attempted to open a Guardian EDIT file for write access or for

Guardian shared or exclusive exclusion access, but the file has already been opened with a Guardian procedure call.

1

34 Hewlett-Packard Company 527186-003

System Functions (a - d) creat(2)

[EINTR]

[EINVAL]

[EIO]

[EISDIR]

A signal was caught during the open operation. This value is returned only for character special files (terminal devices) and for FIFO special files.

One of these conditions exists:

The call attempted to create a directory named lost+found in the root directory of an OSS fileset, or it attempted to create a directory named

/dev, /dev/tty, or /dev/null in the root directory of the OSS file system.

The function call did not specify the mode parameter.

Bits other than the file permission and appropriate file-type flags are set in the mode parameter.

The function attempted to create a Guardian file (that is, a file in the /G file system), but the pathname cannot be mapped to a valid Guardian disk file name.

The function attempted to open a Guardian file (that is, a file in the /G file system) of a type other than those permitted.

The function attempted to create a Guardian temporary file.

A physical input or output error occurred. Data might have been lost during transfer.

One of these conditions exists:

The named file is an OSS directory.

The named file is a Guardian directory (/G or a directory in the /G file system).

[ELOOP]

[EMFILE]

Too many symbolic links were encountered in translating the path parameter.

The system limit for open file descriptors per process has reached the maximum permitted.

[ENAMETOOLONG]

One of these is too long:

The pathname pointed to by the path parameter

A component of the pathname pointed to by the path parameter

The intermediate result of pathname resolution when a symbolic link is part of the path parameter

The pathconf( ) function can be called to obtain the applicable limits.

[ENOENT] One of these conditions exists:

The pathname prefix does not exist.

The path parameter points to an empty string.

527186-003 Hewlett-Packard Company 1

35

creat(2) OSS System Calls Reference Manual

The function attempted to open a file in the Guardian file system, but the specified pathname cannot be mapped to a valid Guardian filename.

The path parameter specifies a file on a remote HP NonStop node, but communication with the remote node has been lost.

[ENOMEM] The system has insufficient resources to allow another open file.

[ENOROOT] The root fileset (fileset 0) is not in the STARTED state.

[ENOSPC] The directory that would contain the new file cannot be extended, and the file does not exist.

[ENOTDIR] A component of the pathname prefix is not a directory.

[ENXIO] One of these conditions exists:

The named file is a character special file, and the device associated with this special file does not exist.

The fileset containing the client’s current working directory or root directory is not mounted.

[EOPNOTSUPP]

The named file is a socket bound to the file system (not an AF_INET socket) and cannot be opened.

[EOSSNOTRUNNING]

A required system process is not running.

[EPERM] One of these conditions exists:

The call attempted to create a file named lost+found in the root directory of an OSS fileset.

The call attempted to create a file in the /E directory.

[EROFS] The named file resides on a read-only fileset, and write access is required.

[ETXTBSY] The file is being executed.

For all other error conditions, errno is set to the appropriate Guardian file-system error number.

Refer to the Guardian Procedure Errors and Messages Manual for more information about a specific Guardian file-system error.

RELATED INFORMATION

Functions: chmod(2), close(2), fcntl(2), lseek(2), mknod(2), open(2), read(2), stat(2),

umask(2), write(2).

STANDARDS CONFORMANCE

The POSIX standards leave some features to the implementing vendor to define. These features are affected in the HP implementation:

The group ID of the new file is determined by the value of the O_ISGID flag in the parent directory.

1

36 Hewlett-Packard Company 527186-003

System Functions (a - d) creat(2)

If bits other than the file permission and appropriate file-type flags are set in the mode parameter, errno is set to [EINVAL].

The O_TRUNC flag is ignored for files other than regular files.

An attempt to open an OSS directory with creat( ) fails.

HP extensions to the XPG4 Version 2 specification are:

Opening Guardian files (that is, files in the /G file system) is supported, as described under Opening Guardian Files in DESCRIPTION.

The errno values [EFAULT], [EFILEBAD], [EFSBAD], [EGUARDIANOPEN], [EIO],

[ELOOP], [EOSSNOTRUNNING], and [EPERM] can be returned.

The file type S_NONSTOP is supported.

527186-003 Hewlett-Packard Company 1

37

dup(2) OSS System Calls Reference Manual

NAME

dup - Duplicates an open file descriptor

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <unistd.h> int dup(

int filedes);

PARAMETERS

filedes

Specifies an open file descriptor obtained from a successful call to the accept( ),

creat( ), dup( ), dup2( ), fcntl( ), open( ), pipe( ), socket( ), or socketpair( ) function.

DESCRIPTION

The dup( ) function returns a new file descriptor for the open file specified by the filedes parameter. This file descriptor:

Is the lowest-numbered available file descriptor

References the same open

Returns the same file pointer as the original file (that is, both file descriptors share one file pointer if the object is a file)

Returns the same access mode (read, write, or read/write)

Returns the same file status flags (that is, both file descriptors share the same file status flags)

Clears the close-on-exec flag (FD_CLOEXEC bit) associated with the new file descriptor so that the file remains open across calls to any function in the exec, tdm_exec, and

tdm_spawn sets of functions

NOTES

The dup( ) function provides an alternative interface to the service provided by the fcntl( ) function by using the F_DUPFD value of the request parameter. The call: fid = dup( file1 ); is equivalent to: fid = fcntl( file1, F_DUPFD, 0 );

RETURN VALUES

Upon successful completion, the dup( ) function returns a new file descriptor. If the dup( ) function fails, the value -1 is returned, and errno is set to indicate the error.

ERRORS

If any of these conditions occurs, the dup( ) function sets errno to the corresponding value:

[EBADF] The filedes parameter is not a valid open file descriptor.

1

38 Hewlett-Packard Company 527186-003

System Functions (a - d) dup(2)

[EISGUARDIAN]

The value used for the filedes parameter is appropriate only in the Guardian environment.

[EMFILE] The number of file descriptors exceeds the maximum number of opens permitted.

[EWRONGID] One of these conditions occurred:

The process attempted an operation on an input/output process (such as a terminal server process) that has failed or is in the down state.

The processor for the disk process of the specified file failed during an input or output operation, and takeover by the backup process occurred.

The open file descriptor has migrated to a new processor, but the new processor lacks a resource or system process needed for using the file descriptor.

The file descriptor specified by the filedes parameter can only be closed.

For all other error conditions, errno is set to the appropriate Guardian file-system error number.

See the Guardian Procedure Errors and Messages Manual for more information about a specific

Guardian file-system error.

RELATED INFORMATION

Functions: close(2), dup2(2), exec(2), fcntl(2), open(2), read(2), tdm_execve(2),

tdm_execvep(2), write(2).

STANDARDS CONFORMANCE

HP extensions to the XPG4 Version 2 specification are:

The errno values [EISGUARDIAN] and [EWRONGID] can be returned.

527186-003 Hewlett-Packard Company 1

39

dup2(2) OSS System Calls Reference Manual

NAME

dup2 - Duplicates and controls an open file descriptor

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <unistd.h> int dup2(

int filedes,

int new);

PARAMETERS

filedes new

Specifies an open file descriptor obtained from a successful call to the accept( ),

creat( ), dup( ), dup2( ), fcntl( ), open( ), pipe( ), socket( ), or socketpair( ) function.

Specifies the open file descriptor that is returned by the dup2( ) function. If this descriptor is already in use, it is first deallocated as if it had been closed.

DESCRIPTION

The dup2( ) function returns a new file descriptor on the open file specified by the filedes parameter. If new is less than 0 (zero) or greater than or equal to the maximum number of opens permitted, dup2( ) returns -1 with errno set to [EBADF].

The new file descriptor:

Is the value specified as the new parameter:

— If filedes is a valid file descriptor and is equal to new, dup2( ) returns new without closing it.

— If filedes is not a valid file descriptor, dup2( ) returns -1 and does not close new.

— The value returned is equal to the value of new upon successful completion, or it is -1 upon failure.

References the same open

Returns the same file pointer as the original file (that is, both file descriptors share one file pointer if the object is a file)

Returns the same access mode (read, write, or read/write)

Returns the same file status flags (that is, both file descriptors share the same file status flags)

Clears the close-on-exec flag (FD_CLOEXEC bit) associated with the new file descriptor so that the file remains open across calls to any function in the exec, tdm_exec, and

tdm_spawn sets of functions

1

40 Hewlett-Packard Company 527186-003

System Functions (a - d) dup2(2)

NOTES

The dup2( ) function provides an alternative interface to the service provided by the fcntl( ) function by using the F_DUPFD value of the request parameter. The call: fid = dup2( file1, file2 ); is equivalent to: close( file2 ); fid = fcntl( file1, F_DUPFD, file2 );

RETURN VALUES

Upon successful completion, the dup2( ) function returns a new file descriptor. Otherwise, the value -1 is returned, and errno is set to indicate the error.

ERRORS

If any of these conditions occurs, the dup2( ) function sets errno to the corresponding value:

[EBADF] One of these conditions exists:

The filedes parameter is not a valid open file descriptor.

The new parameter file descriptor is negative or greater than the maximum number of opens permitted.

[EISGUARDIAN]

The value used for the filedes parameter is appropriate only in the Guardian environment.

[EWRONGID] One of these conditions occurred:

The process attempted an operation on an input/output process (such as a terminal server process) that has failed or is in the down state.

The processor for the disk process of the specified file failed during an input or output operation, and takeover by the backup process occurred.

The open file descriptor has migrated to a new processor, but the new processor lacks a resource or system process needed for using the file descriptor.

The file descriptor specified by the filedes parameter can only be closed.

For all other error conditions, errno is set to the appropriate Guardian file-system error number.

See the Guardian Procedure Errors and Messages Manual for more information about a specific

Guardian file-system error.

RELATED INFORMATION

Functions: close(2), dup(2), exec(2), fcntl(2), open(2), read(2), tdm_execve(2),

tdm_execvep(2), write(2).

STANDARDS CONFORMANCE

The dup2( ) function does not return the errno value [EINTR].

HP extensions to the XPG4 Version 2 specification are:

The errno values [EISGUARDIAN] and [EWRONGID] can be returned.

527186-003 Hewlett-Packard Company 1

41

Section 2. System Functions (e)

This section contains reference pages for Open System Services (OSS) system function calls with names that begin with e. These reference pages reside in the cat2 directory and are sorted alphabetically by U.S. English conventions in this section.

527186-003 Hewlett-Packard Company 2

1

exec(2) OSS System Calls Reference Manual

NAME

exec - Specifies a set of functions that execute a file

DESCRIPTION

The exec set of functions (execl( ), execle( ), execlp( ), execv( ), execve( ), and execvp( )) replace the current process image with a new process image. The new image is constructed from a regular executable file, called a new process image file. The new process image file is formatted as an executable text or binary file in one of the formats recognized by the exec set of functions.

A successful call to any function in the exec set of functions does not return, because the calling process image is overlaid by the new process image.

When a program is executed as a result of a call to a function in the exec set of functions, it is entered as a function call as follows:

int main(

int argc,

char

∗∗

argv[ ],

char

∗∗

env[ ]);

Here, the argc parameter is the argument count, the argv[ ] parameter is an array of character pointers to the arguments themselves, and env[ ] is a pointer to a character array listing the environment variables.

In addition, the following variable is initialized for the new process as a pointer to an array of character pointers to the environment strings:

extern char

∗∗∗∗

environ;

The argv[ ] array is terminated by a null pointer. The null pointer is not counted in argc.

The arguments specified by a program with one of the exec set of functions are passed on to the new process image in the corresponding arguments to the main( ) function.

The env[ ] parameter for the main function is an HP extension and is not the preferred method of obtaining the environment variables for the child process. Use of the **environ array is the preferred method.

For additional information, refer to the reference page for a specific function in the exec set of functions.

RELATED INFORMATION

Commands: eld(1), ld(1), nld(1).

Functions: alarm(3), _exit(2), execl(2), execle(2), execlp(2), execv(2), execve(2), execvp(2),

fcntl(2), fork(2), getenv(3), putenv(3), semget(2), sigaction(2), system(3), tdm_execve(2),

tdm_execvep(2), tdm_fork(2), tdm_spawn(2), tdm_spawnp(2), times(3), ulimit(3), umask(2).

Miscellaneous: environ(5).

2

2 Hewlett-Packard Company 527186-003

System Functions (e) execl(2)

NAME

execl - Executes a file using a pathname, a set of argument strings, and **environ

LIBRARY

G-series native OSS processes: /G/system/sysnn/zossksrl

H-series OSS processes: /G/system/zdllnnn/zosskdll

SYNOPSIS

#include <unistd.h> extern char

∗∗∗∗

environ; int execl( const char

∗∗

path,

const char

∗∗

arg, . . .);

PARAMETERS

**environ

path arg

Points to an array of character pointers to environment strings. The environment strings define the OSS environment for the new process. The environ array is terminated by a null pointer.

The **environ array of the new process is also passed as the env[ ] array in the call to the main( ) function of the new process. Refer to Entering the New Pro-

cess later in this reference page.

Points to a null-terminated string containing a pathname that identifies the new process image file. The pathname is absolute if it starts with a slash (/) character.

Otherwise, the pathname is relative and is resolved by prefixing the current working directory.

If the final component of the path parameter names a symbolic link, the link is traversed and pathname resolution continues.

Points to a null-terminated string containing an argument to be made visible to the main function of the new program. The first such argument should point to the null-terminated string containing the filename of the new process image. The last of these arguments must be a null pointer.

These strings constitute the argument list available to the new process image.

DESCRIPTION

The execl( ) function is one of the exec set of functions. The exec set of functions replace the current process image with a new process image. The new image is constructed from a regular executable file, called a new process image file. The new process image file is formatted as an executable text or binary file in one of the formats recognized by the exec set of functions.

A successful execl( ) function call does not return, because the calling process image is overlaid by the new process image.

Entering the New Process

When a program is executed as a result of a call to a function in the exec set of functions, it is entered as a function call as follows:

int main(

int argc,

char

∗∗

argv[ ],

char

∗∗

env[ ]);

Here, the argc parameter is the argument count, the argv[ ] parameter is an array of character pointers to the arguments themselves, and env[ ] is a pointer to a character array listing the environment variables. The argv[ ] array is terminated by a null pointer. The null pointer is not

527186-003 Hewlett-Packard Company 2

3

execl(2) OSS System Calls Reference Manual

counted in argc.

The arguments specified by a program with one of the exec set of functions are passed on to the new process image in the corresponding arguments to the main( ) function.

The envp[ ] parameter for the main function is an HP extension and is not the preferred method of obtaining the environment variables for the new process. Use of the **environ array is the preferred method.

Passing the Arguments and the Environment

The number of bytes available for the new process’s combined argument and environment lists has a system-imposed limit. This limit, which includes the pointers and the null terminators on the strings, is available by calling the sysconf(_SC_ARG_MAX) function.

Executing a Binary File

If the file specified in the function call is a binary executable file, the function loads the file directly.

Executing a Text File

If the file specified in the function call is not a binary executable file, the function examines the file to determine whether it is an executable text file. The function checks for a header line in the following format:

#! interpreter_name [optional_string]

The #! notation identifies the file as an executable text file. The new process image filename is constructed from the process image filename in the interpreter_name string, treating it like the

path parameter. The arguments passed to the new process are modified as follows:

The argv[0] parameter is set to the name of the interpreter.

If the optional_string portion is present, argv[1] is set to optional_string.

The next element of argv[ ] is set to the original value of path.

The remaining elements of argv[ ] are set to the the second and subsequent values of the

arg parameter.

The first value of arg is discarded.

The S_ISUID and S_ISGID mode bits of an executable text file are honored. Those bits of the

interpreter_name command interpreter are ignored.

When the File Is Invalid

If the process image file is not a valid executable object, or if the text file does not contain the header line, the execl( ) function call fails and sets errno to the value of [ENOEXEC].

Open Files

File descriptors open in the calling process image remain open in the new process image, except for those:

Whose close-on-exec flag FD_CLOEXEC is set (see the fcntl(2) reference page)

Opened using a Guardian function or procedure call

If the process file segment of the new process image is smaller than the process file segment of the calling process image and if the calling process image has a large number of file descriptors open, then the system might not be able to propagate all the open file descriptors to the new process image. When this situation occurs, the function call fails and errno is set to the value of

[EMFILE].

2

4 Hewlett-Packard Company 527186-003

System Functions (e) execl(2)

For those file descriptors that remain open, all attributes of the open file descriptor, including file locks, remain unchanged. All directory streams are closed.

Shared Memory

Any attached shared memory segments are detached by a successful call to a function in the exec set of functions. Refer to the shmat(2) reference page for additional information about shared memory segment use.

Semaphores

Semaphore set IDs attached to a calling process are also attached to the new process. The new process also inherits the adjust-on-exit (semadj) values of the calling process.

Refer to the semget(2) reference page for additional information about semaphore use.

Signals

Signals set to:

The default action (SIG_DFL) in the calling process image are set to the default action in the new process image.

Be ignored (SIG_IGN) by the calling process image are set to be ignored by the new process image.

Cause abnormal termination (SIG_ABORT) in the calling process image are set to that | action in the new process image.

Cause entry into the debugger (SIG_DEBUG) in the calling process image are set to that | action in the new process image.

Be caught by the calling process image are set to the default action in the new process image.

See the signal(4) reference page either online or in the Open System Services System Calls Refer- |

ence Manual.

User ID and Group ID

If the set-user-ID mode bit of the new process image file is set (see the chmod(2) reference page), the effective user ID of the new process image is set to the owner ID of the new process image file. Similarly, if the set-group-ID mode bit of the new process image file is set, the effective group ID of the new process image is set to the group ID of the new process image file.

The real user ID, real group ID, and supplementary group IDs of the new process image remain the same as those of the calling process image. The effective user ID and effective group ID of the new process image are saved (as the saved-set-user ID and the saved-set-group ID) for use by the setuid( ) function.

The _POSIX_SAVED_IDS flag is defined TRUE.

OSS Attributes

The following OSS attributes of the calling process image are unchanged after successful completion of any of the exec set of functions:

OSS process ID (PID)

Parent process ID

Process group ID

527186-003 Hewlett-Packard Company 2

5

execl(2) OSS System Calls Reference Manual

Session membership

Real user ID

Real group ID

Supplementary group IDs

The time left until an alarm clock signal is posted (see the alarm(3) reference page)

Current working directory

Root directory

File mode creation mask (see the umask(2) reference page)

Process signal mask (see the sigprocmask(2) reference page)

Pending signals (see the sigpending(2) reference page)

The tms_utime, tms_stime, tms_cutime, and tms_cstime fields of the tms structure

File size limit (see the ulimit(2) reference page)

Upon successful completion of the function call, the st_atime field of the file is marked for update.

The POSIX.1 standard does not specify the effect on the st_atime field when the function call fails but does find the file. Likewise, the HP implementation does not guarantee the outcome.

Under these circumstances, this field should not be used for further processing.

Guardian Attributes

The newly created OSS process retains the following Guardian attributes of the process that calls one of the exec set of functions:

Priority

Processor on which the process executes

Home terminal

Job ID

DEFINE mode switch

Process access ID (PAID), unless the S_ISUID mode bit of the new image file is set

Security group list

Job ancestor or GMOM

Unread system message index (PCBMCNT)

This attribute assignment is different from the assignment made when creating a new process with Guardian procedures.

Outstanding incoming and outgoing message limits

This attribute assignment is different from the assignment made when creating a new process with Guardian procedures.

2

6 Hewlett-Packard Company 527186-003

System Functions (e) execl(2)

Login, remote, and saveabend flags

File creation mask

The Guardian attributes of the new process differ from those of the calling process in the following ways:

Segments created or shared using Guardian procedure calls such as

SEGMENT_ALLOCATE_ are not inherited.

The program file is the file specified in the function call.

The library file is specified in the program file.

The new process does not inherit the caller’s extended swap file (if any). For a G-series

TNS process or an accelerated process, the extended data segment is managed by the

Kernel Managed Storage Facility (KMSF).

The process name for the new process is system-generated if the RUNNAMED option is set in the program file. Otherwise the process is unnamed.

The size of the data segment of the new process is set in the program file

The remote login flag (PCBREMID) is set to off if the program file has had its S_ISUID mode bit set. Otherwise, the remote login flag is set the same as for the caller.

The size of the extended data segment of the new process is set in the program file

The DEFINEs inherited by the new process depend on the setting of DEFINE mode in the caller. If DEFINE mode in the caller is ON, all the caller’s DEFINEs are inherited.

If DEFINE mode is OFF, no DEFINEs are inherited.

The process identification number (PIN) of the new process is unrelated to that of the calling process. The PIN of the new process is unrestricted if both of the following are true:

— The HIGHPIN flag is set in the program file and any user library file.

— The PIN of the calling process was unrestricted.

If the PIN of the new process is restricted, then the PIN is in the range 0 through 254.

The creator access ID (CAID) is set to the process access ID (PAID) of the calling process.

The PAID depends on whether the S_ISUID mode bit of the image file is set. If so, the

PAID is based on the file owner ID. If not, the PAID is the same as for the caller. (The

S_ISUID mode bit of the image file has no effect on the security group list.)

The MOM field for the new process depends on whether the calling process is named. If so, the MOM field for the new process is set to the caller’s ANCESTOR field. Otherwise, the MOM field for the new process is set to the caller’s MOM field.

System debugger selection for the new process is based on Inspect mode.

Code breakpoints and memory breakpoints are not inherited.

For detailed information about Guardian process attributes, see the PROCESS_LAUNCH_ procedure in the Guardian Procedure Calls Reference Manual.

527186-003 Hewlett-Packard Company 2

7

execl(2) OSS System Calls Reference Manual

Use From the Guardian Environment

If called from a Guardian process, the function call fails and errno is set to [ENOTOSS].

RETURN VALUES

If the execl( ) function returns to the calling process image, an error has occurred; the return value is -1, and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the function sets errno to the corresponding value. For any of these error conditions, file descriptors marked close-on-exec are not closed, signals set to be caught are not set to the default action, and none of the following are changed:

The value of the global variable environ

The pointers contained within the global variable environ

The elements pointed to by environ pointers

The effective user ID of the current process

The effective group ID of the current process

[E2BIG]

[EACCES]

The number of bytes used by the new process image’s argument list and environment list is greater than the system-imposed limit. The limit can be obtained by calling the sysconf(_SC_ARG_MAX) function.

One of the following conditions exists:

Search permission is denied for the directory components of the pathname prefix to the process image file.

The new process image file, any library file, or script file denies execution permission.

The new process image file is not a regular file.

[EAGAIN]

[EFAULT]

[EINVAL]

[ELOOP]

System resources such as disk space, process control block (PCB) space, MAP-

POOL space, stack space, or PFS space are temporarily inadequate.

An input address parameter is outside valid bounds limits.

The new process image file is a binary executable file with invalid attributes.

Too many symbolic links were encountered in pathname resolution.

[EMFILE] The maximum number of files is open. The process attempted to open more than the maximum number of file descriptors allowed for the process. The process file segment (PFS) of the new process might be smaller than that of the calling process.

[ENAMETOOLONG]

One of the following is too long:

The pathname pointed to by the path parameter

A component of the pathname pointed to by the path parameter

2

8 Hewlett-Packard Company 527186-003

System Functions (e) execl(2)

The intermediate result of pathname resolution when a symbolic link is part of the pathname pointed to by the path parameter

The pathconf( ) function can be called to obtain the applicable limits.

[ENODEV] The system cannot find the device containing the fileset containing the process image file.

[ENOENT] One of the following conditions exists:

One or more components of the new process image file’s pathname do not exist.

The path parameter points to an empty string.

[ENOEXEC] The new process image file has the appropriate access permissions, but it is neither in the correct binary executable format nor a valid executable text file.

[ENOMEM] Required resources are not available. Subsequent calls to the same function will not succeed for the same reason.

Possible causes of this error include insufficient primary memory (stack, globals, or heap) for the new process.

[ENOTDIR] A component of the path prefix of the new process image file is not a directory.

[ENOTOSS] The calling process is not an OSS process. A function in the exec set of functions cannot be called from the Guardian environment.

[ETXTBSY] The new process image file is currently open for writing by a process.

[EUNKNOWN]

Unknown error. An unrecognized or very obscure error occurred. If this error occurs, follow site-defined procedures for reporting software problems to

HP.

RELATED INFORMATION

Commands: eld(1), ld(1), nld(1).

Functions: alarm(3), _exit(2), execle(2), execlp(2), execv(2), execve(2), execvp(2, fcntl(2),

fork(2), getenv(3), putenv(3), semget(2), sigaction(2), system(3), tdm_execve(2),

tdm_execvep(2), tdm_fork(2), tdm_spawn(2), tdm_spawnp(2), times(3), ulimit(3), umask(2).

Miscellaneous: environ(5).

STANDARDS CONFORMANCE

The POSIX standards leave some features to the implementing vendor to define. The following features are affected in the HP implementation:

Guardian attributes are associated with the new OSS process. See Guardian Attributes under DESCRIPTION.

The contents of the st_atime field following a failed function call in which the file was found should not be depended upon for further processing.

The use of *env[ ] as a parameter in the call to main( ) is an

HP extension.

527186-003 Hewlett-Packard Company 2

9

execl(2) OSS System Calls Reference Manual

The following are HP extensions to the XPG4 Version 2 specification:

Text files containing the #! interpreter_name [optional_string] header line can execute.

The [EINVAL], [ENODEV], [ENOTOSS], and [EUNKNOWN] error values are an

HP extension.

2

10 Hewlett-Packard Company 527186-003

System Functions (e) execle(2)

NAME

execle - Executes a file using a pathname, a set of argument strings, and an undeclared envp array

LIBRARY

G-series native OSS processes: /G/system/sysnn/zossksrl

H-series OSS processes: /G/system/zdllnnn/zosskdll

SYNOPSIS

#include <unistd.h> extern char

∗∗∗∗

environ; int execle( const char

∗∗

path,

const char

∗∗

arg, . . .

/*

, (char *)0, char *const envp[ ]

*/

);

PARAMETERS

**environ

Points to an array of character pointers to environment strings. The environment strings define the OSS environment for the calling process. The environ array is terminated by a null pointer.

When the new process is created, the corresponding **environ array is not initialized for it with the content of the **environ array of the calling process.

Instead, the undeclared envp[ ] array that can follow the arg parameter list is written into the **environ array of the new process when the execle( ) function call is processed.

The **environ array of the new process is also passed as the env[ ] array in the call to the main( ) function of the new process. Refer to Entering the New Pro-

cess later in this reference page.

path

Points to a null-terminated string containing a pathname that identifies the new process image file. The pathname is absolute if it starts with a slash (/) character.

Otherwise, the pathname is relative and is resolved by prefixing the current working directory.

If the final component of the path parameter names a symbolic link, the link is traversed and pathname resolution continues.

arg

Points to a null-terminated string containing an argument to be made visible to the main function of the new program. The first such argument should point to the null-terminated string containing the filename of the new process image. The last of these arguments must be a null pointer.

These strings constitute the argument list available to the new process image.

DESCRIPTION

The execle( ) function is one of the exec set of functions. The exec set of functions replace the current process image with a new process image. The new image is constructed from a regular executable file, called a new process image file. The new process image file is formatted as an executable text or binary file in one of the formats recognized by the exec set of functions.

A successful execle( ) function call does not return, because the calling process image is overlaid by the new process image.

527186-003 Hewlett-Packard Company 2

11

execle(2) OSS System Calls Reference Manual

Entering the New Process

When a program is executed as a result of a call to a function in the exec set of functions, it is entered as a function call as follows:

int main(

int argc,

char

∗∗

argv[ ],

char

∗∗

env[ ]);

Here, the argc parameter is the argument count, the argv[ ] parameter is an array of character pointers to the arguments themselves, and env[ ] is a pointer to a character array listing the environment variables. The argv[ ] array is terminated by a null pointer. The null pointer is not counted in argc.

The arguments specified by a program with one of the exec set of functions are passed on to the new process image in the corresponding arguments to the main( ) function.

The env[ ] parameter for the main function is an HP extension and is not the preferred method of obtaining the environment variables for the new process. Use of the the **environ array of the new process is the preferred method.

Passing the Arguments and the Environment

Instead of passing the **environ array of the calling process, the environment for the new process is provided by following the null pointer that terminates the list of arg parameters with an additional parameter as if it were declared as:

char

∗∗

const envp[ ]

The envp[ ] parameter names an array of character pointers to null-terminated strings. These strings constitute the environment for the new process image. The environment array is terminated with a null pointer.

The number of bytes available for the new process’s combined argument and environment lists has a system-imposed limit. This limit, which includes the pointers and the null terminators on the strings, is available by calling the sysconf(_SC_ARG_MAX) function.

Executing a Binary File

If the file specified in the function call is a binary executable file, the function loads the file directly.

Executing a Text File

If the file specified in the function call is not a binary executable file, the function examines the file to determine whether it is an executable text file. The function checks for a header line in the following format:

#! interpreter_name [optional_string]

The #! notation identifies the file as an executable text file. The new process image filename is constructed from the process image filename in the interpreter_name string, treating it like the

path parameter. The arguments passed to the new process are modified as follows:

The argv[0] parameter is set to the name of the interpreter.

If the optional_string portion is present, argv[1] is set to optional_string.

The next element of argv[ ] is set to the original value of path.

The remaining elements of argv[ ] are set to the original elements of argv[ ], starting with the second and subsequent values of the arg parameter.

2

12 Hewlett-Packard Company 527186-003

System Functions (e) execle(2)

The first value of arg is discarded.

The S_ISUID and S_ISGID mode bits of an executable text file are honored. Those bits of the

interpreter_name command interpreter are ignored.

When the File Is Invalid

If the process image file is not a valid executable object, or if the text file does not contain the header line, the execle( ) function call fails and sets errno to the value of [ENOEXEC].

Open Files

File descriptors open in the calling process image remain open in the new process image, except for those:

Whose close-on-exec flag FD_CLOEXEC is set (see the fcntl(2) reference page)

Opened using a Guardian function or procedure call

If the process file segment of the new process image is smaller than the process file segment of the calling process image and if the calling process image has a large number of file descriptors open, then the system might not be able to propagate all the open file descriptors to the new process image. When this situation occurs, the function call fails and errno is set to the value of

[EMFILE].

For those file descriptors that remain open, all attributes of the open file descriptor, including file locks, remain unchanged. All directory streams are closed.

Shared Memory

Any attached shared memory segments are detached by a successful call to a function in the exec set of functions. Refer to the shmat(2) reference page for additional information about shared memory segment use.

Semaphores

Semaphore set IDs attached to a calling process are also attached to the new process. The new process also inherits the adjust-on-exit (semadj) values of the calling process.

Refer to the semget(2) reference page for additional information about semaphore use.

Signals

Signals set to:

The default action (SIG_DFL) in the calling process image are set to the default action in the new process image.

Be ignored (SIG_IGN) by the calling process image are set to be ignored by the new process image.

Cause abnormal termination (SIG_ABORT) in the calling process image are set to that | action in the new process image.

Cause entry into the debugger (SIG_DEBUG) in the calling process image are set to that | action in the new process image.

Be caught by the calling process image are set to the default action in the new process image.

See the signal(4) reference page either online or in the Open System Services System Calls Refer- |

ence Manual.

527186-003 Hewlett-Packard Company 2

13

execle(2) OSS System Calls Reference Manual

User ID and Group ID

If the set-user-ID mode bit of the new process image file is set (see the chmod(2) reference page), the effective user ID of the new process image is set to the owner ID of the new process image file. Similarly, if the set-group-ID mode bit of the new process image file is set, the effective group ID of the new process image is set to the group ID of the new process image file.

The real user ID, real group ID, and supplementary group IDs of the new process image remain the same as those of the calling process image. The effective user ID and effective group ID of the new process image are saved (as the saved-set-user ID and the saved-set-group ID) for use by the setuid( ) function.

The _POSIX_SAVED_IDS flag is defined TRUE.

OSS Attributes

The following OSS attributes of the calling process image are unchanged after successful completion of any of the exec set of functions:

OSS process ID (PID)

Parent process ID

Process group ID

Session membership

Real user ID

Real group ID

Supplementary group IDs

The time left until an alarm clock signal is posted (see the alarm(3) reference page)

Current working directory

Root directory

File mode creation mask (see the umask(2) reference page)

Process signal mask (see the sigprocmask(2) reference page)

Pending signals (see the sigpending(2) reference page)

The tms_utime, tms_stime, tms_cutime, and tms_cstime fields of the tms structure

File size limit (see the ulimit(2) reference page)

Upon successful completion of the function call, the st_atime field of the file is marked for update.

The POSIX.1 standard does not specify the effect on the st_atime field when the function call fails but does find the file. Likewise, the HP implementation does not guarantee the outcome.

Under these circumstances, this field should not be used for further processing.

Guardian Attributes

The newly created OSS process retains the following Guardian attributes of the process that calls one of the exec set of functions:

Priority

Processor on which the process executes

2

14 Hewlett-Packard Company 527186-003

System Functions (e) execle(2)

Home terminal

Job ID

DEFINE mode switch

Process access ID (PAID), unless the S_ISUID mode bit of the new image file is set

Security group list

Job ancestor or GMOM

Unread system message index (PCBMCNT)

This attribute assignment is different from the assignment made when creating a new process with Guardian procedures.

Outstanding incoming and outgoing message limits

This attribute assignment is different from the assignment made when creating a new process with Guardian procedures.

Login, remote, and saveabend flags

File creation mask

The Guardian attributes of the new process differ from those of the calling process in the following ways:

Segments created or shared using Guardian procedure calls such as

SEGMENT_ALLOCATE_ are not inherited.

The program file is the file specified in the function call.

The library file is specified in the program file.

The new process does not inherit the caller’s extended swap file (if any). For a G-series

TNS process or an accelerated process, the extended data segment is managed by the

Kernel Managed Storage Facility (KMSF).

The process name for the new process is system-generated if the RUNNAMED option is set in the program file. Otherwise the process is unnamed.

The size of the data segment of the new process is set in the program file.

The remote login flag (PCBREMID) is set to off if the program file has had its S_ISUID mode bit set. Otherwise, the remote login flag is set the same as for the caller.

The size of the extended data segment of the new process is set in the program file.

The DEFINEs inherited by the new process depend on the setting of DEFINE mode in the caller. If DEFINE mode in the caller is ON, all the caller’s DEFINEs are inherited.

If DEFINE mode is OFF, no DEFINEs are inherited.

The process identification number (PIN) of the new process is unrelated to that of the calling process. The PIN of the new process is unrestricted if both of the following are true:

— The HIGHPIN flag is set in the program file and any user library file.

— The PIN of the calling process was unrestricted.

If the PIN of the new process is restricted, then the PIN is in the range 0 through 254.

527186-003 Hewlett-Packard Company 2

15

execle(2) OSS System Calls Reference Manual

The creator access ID (CAID) is set to the process access ID (PAID) of the calling process.

The PAID depends on whether the S_ISUID mode bit of the image file is set. If so, the

PAID is based on the file owner ID. If not, the PAID is the same as for the caller. (The

S_ISUID mode bit of the image file has no effect on the security group list.)

The MOM field for the new process depends on whether the calling process is named. If so, the MOM field for the new process is set to the caller’s ANCESTOR field. Otherwise, the MOM field for the new process is set to the caller’s MOM field.

System debugger selection for the new process is based on Inspect mode.

Code breakpoints and memory breakpoints are not inherited.

For detailed information about Guardian process attributes, see the PROCESS_LAUNCH_ procedure in the Guardian Procedure Calls Reference Manual.

Use From the Guardian Environment

If called from a Guardian process, the function call fails and errno is set to [ENOTOSS].

RETURN VALUES

If the execle( ) function returns to the calling process image, an error has occurred; the return value is -1, and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the function sets errno to the corresponding value. For any of these error conditions, file descriptors marked close-on-exec are not closed, signals set to be caught are not set to the default action, and none of the following are changed:

The envp[ ] array of pointers

The elements pointed to by this array

The effective user ID of the current process

The effective group ID of the current process

[E2BIG]

[EACCES]

The number of bytes used by the new process image’s argument list and environment list is greater than the system-imposed limit. The limit can be obtained by calling the sysconf(_SC_ARG_MAX) function.

One of the following conditions exists:

Search permission is denied for the directory components of the pathname prefix to the process image file.

The new process image file, any library file, or script file denies execution permission.

The new process image file is not a regular file.

[EAGAIN] System resources such as disk space, process control block (PCB) space, MAP-

POOL space, stack space, or PFS space are temporarily inadequate.

2

16 Hewlett-Packard Company 527186-003

System Functions (e) execle(2)

[EFAULT]

[EINVAL]

[ELOOP]

An input address parameter is outside valid bounds limits.

The new process image file is a binary executable file with invalid attributes.

Too many symbolic links were encountered in pathname resolution.

[EMFILE] The maximum number of files is open. The process attempted to open more than the maximum number of file descriptors allowed for the process. The process file segment (PFS) of the new process might be smaller than that of the calling process.

[ENAMETOOLONG]

One of the following is too long:

The pathname pointed to by the path parameter

A component of the pathname pointed to by the path parameter

The intermediate result of pathname resolution when a symbolic link is part of the pathname pointed to by the path parameter

The pathconf( ) function can be called to obtain the applicable limits.

[ENODEV] The system cannot find the device containing the fileset containing the process image file.

[ENOENT] One of the following conditions exists:

One or more components of the new process image file’s pathname do not exist.

The path parameter points to an empty string.

[ENOEXEC] The new process image file has the appropriate access permissions, but it is neither in the correct binary executable format nor a valid executable text file.

[ENOMEM] Required resources are not available. Subsequent calls to the same function will not succeed for the same reason.

Possible causes of this error include insufficient primary memory (stack, globals, or heap) for the new process.

[ENOTDIR] A component of the path prefix of the new process image file is not a directory.

[ENOTOSS] The calling process is not an OSS process. A function in the exec set of functions cannot be called from the Guardian environment.

[ETXTBSY] The new process image file is currently open for writing by a process.

[EUNKNOWN]

Unknown error. An unrecognized or very obscure error occurred. If this error occurs, follow site-defined procedures for reporting software problems to

HP.

RELATED INFORMATION

Commands: eld(1), ld(1), nld(1).

Functions: alarm(3), _exit(2), execl(2), execlp(2), execv(2), execve(2), execvp(2), execl(2),

fcntl(2), fork(2), getenv(3), putenv(3), semget(2), sigaction(2), system(3), tdm_execve(2),

tdm_execvep(2), tdm_fork(2), tdm_spawn(2), tdm_spawnp(2), times(3), ulimit(3), umask(2).

527186-003 Hewlett-Packard Company 2

17

execle(2) OSS System Calls Reference Manual

Miscellaneous: environ(5).

STANDARDS CONFORMANCE

The POSIX standards leave some features to the implementing vendor to define. The following features are affected in the HP implementation:

Guardian attributes are associated with the new OSS process. See Guardian Attributes under DESCRIPTION.

The contents of the st_atime field following a failed function call in which the file was found should not be depended upon for further processing.

The use of *env[ ] as a parameter in the call to main( ) is an HP extension.

The following are HP extensions to the XPG4 Version 2 specification:

Text files containing the #! interpreter_name [optional_string] header line can execute.

The [EINVAL], [ENODEV], [ENOTOSS], and [EUNKNOWN] error values are an

HP extension.

2

18 Hewlett-Packard Company 527186-003

System Functions (e) execlp(2)

NAME

execlp - Executes a file using a filename, a set of argument strings, and **environ

LIBRARY

G-series native OSS processes: /G/system/sysnn/zossksrl

H-series OSS processes: /G/system/zdllnnn/zosskdll

SYNOPSIS

#include <unistd.h> extern char

∗∗∗∗

environ; int execlp( const char

∗∗

file,

const char

∗∗

arg, . . .);

PARAMETERS

**environ

file

Points to an array of character pointers to environment strings. The environment strings define the OSS environment for the new process. The environ array is terminated by a null pointer.

The **environ array of the new process is also passed as the env[ ] array in the call to the main( ) function of the new process. Refer to Entering the New Pro-

cess later in this reference page.

Identifies the new process image file. If this parameter

Starts with a slash (/) character, then it contains the absolute pathname.

Does not start with a slash but does contain a slash, then the pathname resolves relative to the current working directory.

Contains no slash, the system searches the directories listed in the PATH environment variable for the file and prefixes the directory in which it is found.

arg

Points to a null-terminated string containing an argument to be made visible to the main function of the new program. The first such argument should point to the null-terminated string containing the filename of the new process image. The last of these arguments must be a null pointer.

These strings constitute the argument list available to the new process image.

DESCRIPTION

The execlp( ) function is one of the exec set of functions. The exec set of functions replace the current process image with a new process image. The new image is constructed from a regular executable file, called a new process image file. The new process image file is formatted as an executable text or binary file in one of the formats recognized by the exec set of functions.

A successful execlp( ) function call does not return, because the calling process image is overlaid by the new process image.

527186-003 Hewlett-Packard Company 2

19

execlp(2) OSS System Calls Reference Manual

Entering the New Process

When a program is executed as a result of a call to a function in the exec set of functions, it is entered as a function call as follows:

int main(

int argc,

char

∗∗

argv[ ],

char

∗∗

env[ ]);

Here, the argc parameter is the argument count, the argv[ ] parameter is an array of character pointers to the arguments themselves, and env[ ] is a pointer to a character array listing the environment variables. The argv[ ] array is terminated by a null pointer. The null pointer is not counted in argc.

The arguments specified by a program with one of the exec set of functions are passed on to the new process image in the corresponding arguments to the main( ) function.

The env[ ] parameter for the main function is an HP extension and is not the preferred method of obtaining the environment variables for the new process. Use of the **environ array is the preferred method.

Passing the Arguments and the Environment

The number of bytes available for the new process’s combined argument and environment lists has a system-imposed limit. This limit, which includes the pointers and the null terminators on the strings, is available by calling the sysconf(_SC_ARG_MAX) function.

Executing a Binary File

If the file specified in the function call is a binary executable file, the function loads the file directly.

Executing a Text File

If the file specified in the function call is not a binary executable file, the function examines the file to determine whether it is an executable text file. The function checks for a header line in the following format:

#! interpreter_name [optional_string]

The #! notation identifies the file as an executable text file. The new process image filename is constructed from the process image filename in the interpreter_name string, treating it like the

path parameter. The arguments passed to the new process are modified as follows:

The argv[0] parameter is set to the name of the interpreter.

If the optional_string portion is present, argv[1] is set to optional_string.

The next element of argv[ ] is set to the original value of file.

The remaining elements of argv[ ] are set to the original elements of argv[ ], starting with the second and subsequent values of the arg parameter.

The first value of arg is discarded.

The S_ISUID and S_ISGID mode bits of an executable text file are honored. Those bits of the

interpreter_name command interpreter are ignored.

When the File Is Invalid

If the process image file is not a valid executable object, or if the text file does not contain the header line, the execlp( ) function invokes the /bin/sh command interpreter as the new process image and pass the following arguments to it:

2

20 Hewlett-Packard Company 527186-003

System Functions (e) execlp(2)

argv[0] is set to the string "sh".

argv[1] is set to the original value of the file parameter.

The remaining elements of argv[ ] are set to the second and subsequent values of the arg parameter.

The first instance of arg is discarded.

Open Files

File descriptors open in the calling process image remain open in the new process image, except for those:

Whose close-on-exec flag FD_CLOEXEC is set (see the fcntl(2) reference page)

Opened using a Guardian function or procedure call

If the process file segment of the new process image is smaller than the process file segment of the calling process image and if the calling process image has a large number of file descriptors open, then the system might not be able to propagate all the open file descriptors to the new process image. When this situation occurs, the function call fails and errno is set to the value of

[EMFILE].

For those file descriptors that remain open, all attributes of the open file descriptor, including file locks, remain unchanged. All directory streams are closed.

Shared Memory

Any attached shared memory segments are detached by a successful call to a function in the exec set of functions. Refer to the shmat(2) reference page for additional information about shared memory segment use.

Semaphores

Semaphore set IDs attached to a calling process are also attached to the new process. The new process also inherits the adjust-on-exit (semadj) values of the calling process.

Refer to the semget(2) reference page for additional information about semaphore use.

Signals

Signals set to:

The default action (SIG_DFL) in the calling process image are set to the default action in the new process image.

Be ignored (SIG_IGN) by the calling process image are set to be ignored by the new process image.

Cause abnormal termination (SIG_ABORT) in the calling process image are set to that | action in the new process image.

Cause entry into the debugger (SIG_DEBUG) in the calling process image are set to that | action in the new process image.

Be caught by the calling process image are set to the default action in the new process image.

See the signal(4) reference page either online or in the Open System Services System Calls Refer- |

ence Manual.

527186-003 Hewlett-Packard Company 2

21

execlp(2) OSS System Calls Reference Manual

User ID and Group ID

If the set-user-ID mode bit of the new process image file is set (see the chmod(2) reference page), the effective user ID of the new process image is set to the owner ID of the new process image file. Similarly, if the set-group-ID mode bit of the new process image file is set, the effective group ID of the new process image is set to the group ID of the new process image file.

The real user ID, real group ID, and supplementary group IDs of the new process image remain the same as those of the calling process image. The effective user ID and effective group ID of the new process image are saved (as the saved-set-user ID and the saved-set-group ID) for use by the setuid( ) function.

The _POSIX_SAVED_IDS flag is defined TRUE.

OSS Attributes

The following OSS attributes of the calling process image are unchanged after successful completion of any of the exec set of functions:

OSS process ID (PID)

Parent process ID

Process group ID

Session membership

Real user ID

Real group ID

Supplementary group IDs

The time left until an alarm clock signal is posted (see the alarm(3) reference page)

Current working directory

Root directory

File mode creation mask (see the umask(2) reference page)

Process signal mask (see the sigprocmask(2) reference page)

Pending signals (see the sigpending(2) reference page)

The tms_utime, tms_stime, tms_cutime, and tms_cstime fields of the tms structure

File size limit (see the ulimit(2) reference page)

Upon successful completion of the function call, the st_atime field of the file is marked for update.

The POSIX.1 standard does not specify the effect on the st_atime field when the function call fails but does find the file. Likewise, the HP implementation does not guarantee the outcome.

Under these circumstances, this field should not be used for further processing.

Guardian Attributes

The newly created OSS process retains the following Guardian attributes of the process that calls one of the exec set of functions:

Priority

Processor on which the process executes

2

22 Hewlett-Packard Company 527186-003

System Functions (e) execlp(2)

Home terminal

Job ID

DEFINE mode switch

Process access ID (PAID), unless the S_ISUID mode bit of the new image file is set

Security group list

Job ancestor or GMOM

Unread system message index (PCBMCNT)

This attribute assignment is different from the assignment made when creating a new process with Guardian procedures.

Outstanding incoming and outgoing message limits

This attribute assignment is different from the assignment made when creating a new process with Guardian procedures.

Login, remote, and saveabend flags

File creation mask

The Guardian attributes of the new process differ from those of the calling process in the following ways:

Segments created or shared using Guardian procedure calls such as

SEGMENT_ALLOCATE_ are not inherited.

The program file is the file specified in the function call.

The library file is specified in the program file.

The new process does not inherit the caller’s extended swap file (if any). For a G-series

TNS process or an accelerated process, the extended data segment is managed by the

Kernel Managed Storage Facility (KMSF).

The process name for the new process is system-generated if the RUNNAMED option is set in the program file. Otherwise the process is unnamed.

The size of the data segment of the new process is set in the program file.

The remote login flag (PCBREMID) is set to off if the program file has had its S_ISUID mode bit set. Otherwise, the remote login flag is set the same as for the caller.

The size of the extended data segment of the new process is set in the program file.

The DEFINEs inherited by the new process depend on the setting of DEFINE mode in the caller. If DEFINE mode in the caller is ON, all the caller’s DEFINEs are inherited.

If DEFINE mode is OFF, no DEFINEs are inherited.

The process identification number (PIN) of the new process is unrelated to that of the calling process. The PIN of the new process is unrestricted if both of the following are true:

— The HIGHPIN flag is set in the program file and any user library file.

— The PIN of the calling process was unrestricted.

If the PIN of the new process is restricted, then the PIN is in the range 0 through 254.

527186-003 Hewlett-Packard Company 2

23

execlp(2) OSS System Calls Reference Manual

The creator access ID (CAID) is set to the process access ID (PAID) of the calling process.

The PAID depends on whether the S_ISUID mode bit of the image file is set. If so, the

PAID is based on the file owner ID. If not, the PAID is the same as for the caller. (The

S_ISUID mode bit of the image file has no effect on the security group list.)

The MOM field for the new process depends on whether the calling process is named. If so, the MOM field for the new process is set to the caller’s ANCESTOR field. Otherwise, the MOM field for the new process is set to the caller’s MOM field.

System debugger selection for the new process is based on Inspect mode.

Code breakpoints and memory breakpoints are not inherited.

For detailed information about Guardian process attributes, see the PROCESS_LAUNCH_ procedure in the Guardian Procedure Calls Reference Manual.

Use From the Guardian Environment

If called from a Guardian process, the function call fails and errno is set to [ENOTOSS].

RETURN VALUES

If the execlp( ) function returns to the calling process image, an error has occurred; the return value is -1, and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the function sets errno to the corresponding value. For any of these error conditions, file descriptors marked close-on-exec are not closed, signals set to be caught are not set to the default action, and none of the following are changed:

The value of the global variable environ

The pointers contained within the global variable environ

The elements pointed to by environ pointers

The effective user ID of the current process

The effective group ID of the current process

[E2BIG]

[EACCES]

The number of bytes used by the new process image’s argument list and environment list is greater than the system-imposed limit. The limit can be obtained by calling the sysconf(_SC_ARG_MAX) function.

One of the following conditions exists:

Search permission is denied for the directory components of the pathname prefix to the process image file.

The new process image file, any library file, or script file denies execution permission.

The new process image file is not a regular file.

[EAGAIN] System resources such as disk space, process control block (PCB) space, MAP-

POOL space, stack space, or PFS space are temporarily inadequate.

2

24 Hewlett-Packard Company 527186-003

System Functions (e) execlp(2)

[EFAULT]

[EINVAL]

[ELOOP]

An input address parameter is outside valid bounds limits.

The new process image file is a binary executable file with invalid attributes.

Too many symbolic links were encountered in pathname resolution.

[EMFILE] The maximum number of files is open. The process attempted to open more than the maximum number of file descriptors allowed for the process. The process file segment (PFS) of the new process might be smaller than that of the calling process.

[ENAMETOOLONG]

One of the following is too long:

The filename pointed to by the file parameter

The intermediate result of pathname resolution when a symbolic link is part of the value specified for the file parameter

The pathconf( ) function can be called to obtain the applicable limits.

[ENODEV] The system cannot find the device containing the fileset containing the process image file.

[ENOENT] The file parameter points to an empty string.

[ENOEXEC] The new process image file has the appropriate access permissions, but it is neither in the correct binary executable format nor a valid executable text file. The

/bin/sh command interpreter could not be invoked as a substitute.

[ENOMEM] Required resources are not available. Subsequent calls to the same function will not succeed for the same reason.

Possible causes of this error include insufficient primary memory (stack, globals, or heap) for the new process.

[ENOTOSS] The calling process is not an OSS process. A function in the exec set of functions cannot be called from the Guardian environment.

[ETXTBSY] The new process image file is currently open for writing by a process.

[EUNKNOWN]

Unknown error. An unrecognized or very obscure error occurred. If this error occurs, follow site-defined procedures for reporting software problems to

HP.

RELATED INFORMATION

Commands: nld(1).

Functions: alarm(3), _exit(2), execl(2), execle(2), execv(2), execve(2), execvp(2), fcntl(2),

fork(2), getenv(3), putenv(3), semget(2), sigaction(2), system(3), tdm_execve(2),

tdm_execvep(2), tdm_fork(2), tdm_spawn(2), tdm_spawnp(2), times(3), ulimit(3), umask(2).

Miscellaneous: environ(5).

527186-003 Hewlett-Packard Company 2

25

execlp(2) OSS System Calls Reference Manual

STANDARDS CONFORMANCE

The POSIX standards leave some features to the implementing vendor to define. The following features are affected in the HP implementation:

Guardian attributes are associated with the new OSS process. See Guardian Attributes under DESCRIPTION.

[ENOENT] is returned in errno if the environment variable PATH is not defined when the execlp( ) function is called.

The contents of the st_atime field following a failed function call in which the file was found should not be depended upon for further processing.

The use of *env[ ] as a parameter in the call to main( ) is an HP extension.

The following are HP extensions to the XPG4 Version 2 specification:

Text files containing the #! interpreter_name [optional_string] header line can execute.

The [EINVAL], [ENODEV], [ENOTOSS], and [EUNKNOWN] error values are an HP extension.

2

26 Hewlett-Packard Company 527186-003

System Functions (e) execv(2)

NAME

execv - Executes a file using a pathname, an argv array, and **environ

LIBRARY

G-series native OSS processes: /G/system/sysnn/zossksrl

H-series OSS processes: /G/system/zdllnnn/zosskdll

SYNOPSIS

#include <unistd.h> extern char

∗∗∗∗

environ; int execv( const char

∗∗

path,

char

∗∗

const argv[ ]);

PARAMETERS

**environ

path

argv[ ]

Points to an array of character pointers to environment strings. The environment strings define the OSS environment for the new process. The environ array is terminated by a null pointer.

The **environ array of the new process is also passed as the env[ ] array in the call to the main( ) function of the new process. Refer to Entering the New Pro-

cess later in this reference page.

Points to a null-terminated string containing a pathname that identifies the new process image file. The pathname is absolute if it starts with a slash (/) character.

Otherwise, the pathname is relative and is resolved by prefixing the current working directory.

If the final component of the path parameter names a symbolic link, the link is traversed and pathname resolution continues.

Specifies an array of character pointers to null-terminated strings containing arguments to be passed to the main function of the new program. argv[0] should point to the null-terminated string containing the filename of the new process image. The last member of this array must be a null pointer.

These strings constitute the argument list available to the new process image.

DESCRIPTION

The execv( ) function is one of the exec set of functions. The exec set of functions replace the current process image with a new process image. The new image is constructed from a regular executable file, called a new process image file. The new process image file is formatted as an executable text or binary file in one of the formats recognized by the exec set of functions.

A successful execv( ) function call does not return, because the calling process image is overlaid by the new process image.

Entering the New Process

When a program is executed as a result of a call to a function in the exec set of functions, it is entered as a function call as follows:

int main(

int argc,

char

∗∗

argv[ ],

char

∗∗

env[ ]);

Here, the argc parameter is the argument count, the argv[ ] parameter is an array of character pointers to the arguments themselves, and env[ ] is a pointer to a character array listing the environment variables. The argv[ ] array is terminated by a null pointer. The null pointer is not

527186-003 Hewlett-Packard Company 2

27

execv(2) OSS System Calls Reference Manual

counted in argc.

The arguments specified by a program with one of the exec set of functions are passed on to the new process image in the corresponding arguments to the main( ) function.

The env[ ] parameter for the main function is an HP extension and is not the preferred method of obtaining the environment variables for the new process. Use of the **environ array is the preferred method.

Passing the Arguments and the Environment

The number of bytes available for the new process’s combined argument and environment lists has a system-imposed limit. This limit, which includes the pointers and the null terminators on the strings, is available by calling the sysconf(_SC_ARG_MAX) function.

Executing a Binary File

If the file specified in the function call is a binary executable file, the function loads the file directly.

Executing a Text File

If the file specified in the function call is not a binary executable file, all forms of the function examine the file to determine whether it is an executable text file. The function checks for a header line in the following format:

#! interpreter_name [optional_string]

The #! notation identifies the file as an executable text file. The new process image filename is constructed from the process image filename in the interpreter_name string, treating it like the

path parameter. The arguments passed to the new process are modified as follows:

The argv[0] parameter is set to the name of the interpreter.

If the optional_string portion is present, argv[1] is set to optional_string.

The next element of argv[ ] is set to the original value of path).

The remaining elements of argv[ ] are set to the original elements of argv[ ], starting with

argv[1].

The original argv[0] is discarded.

The S_ISUID and S_ISGID mode bits of an executable text file are honored. Those bits of the

interpreter_name command interpreter are ignored.

When the File Is Invalid

If the process image file is not a valid executable object, or if the text file does not contain the header line, the execv( ) function call fails and errno is set to the value of [ENOEXEC].

Open Files

File descriptors open in the calling process image remain open in the new process image, except for those:

Whose close-on-exec flag FD_CLOEXEC is set (see the fcntl(2) reference page)

Opened using a Guardian function or procedure call

If the process file segment of the new process image is smaller than the process file segment of the calling process image and if the calling process image has a large number of file descriptors open, then the system might not be able to propagate all the open file descriptors to the new process image. When this situation occurs, the function call fails and errno is set to the value of

[EMFILE].

2

28 Hewlett-Packard Company 527186-003

System Functions (e) execv(2)

For those file descriptors that remain open, all attributes of the open file descriptor, including file locks, remain unchanged. All directory streams are closed.

Shared Memory

Any attached shared memory segments are detached by a successful call to a function in the exec set of functions. Refer to the shmat(2) reference page for additional information about shared memory segment use.

Semaphores

Semaphore set IDs attached to a calling process are also attached to the new process. The new process also inherits the adjust-on-exit (semadj) values of the calling process.

Refer to the semget(2) reference page for additional information about semaphore use.

Signals

Signals set to:

The default action (SIG_DFL) in the calling process image are set to the default action in the new process image.

Be ignored (SIG_IGN) by the calling process image are set to be ignored by the new process image.

Cause abnormal termination (SIG_ABORT) in the calling process image are set to that | action in the new process image.

Cause entry into the debugger (SIG_DEBUG) in the calling process image are set to that | action in the new process image.

Be caught by the calling process image are set to the default action in the new process image.

See the signal(4) reference page either online or in the Open System Services System Calls Refer- |

ence Manual.

User ID and Group ID

If the set-user-ID mode bit of the new process image file is set (see the chmod(2) reference page), the effective user ID of the new process image is set to the owner ID of the new process image file. Similarly, if the set-group-ID mode bit of the new process image file is set, the effective group ID of the new process image is set to the group ID of the new process image file.

The real user ID, real group ID, and supplementary group IDs of the new process image remain the same as those of the calling process image. The effective user ID and effective group ID of the new process image are saved (as the saved-set-user ID and the saved-set-group ID) for use by the setuid( ) function.

The _POSIX_SAVED_IDS flag is defined TRUE.

OSS Attributes

The following OSS attributes of the calling process image are unchanged after successful completion of any of the exec set of functions:

OSS process ID (PID)

Parent process ID

Process group ID

527186-003 Hewlett-Packard Company 2

29

execv(2) OSS System Calls Reference Manual

Session membership

Real user ID

Real group ID

Supplementary group IDs

The time left until an alarm clock signal is posted (see the alarm(3) reference page)

Current working directory

Root directory

File mode creation mask (see the umask(2) reference page)

Process signal mask (see the sigprocmask(2) reference page)

Pending signals (see the sigpending(2) reference page)

The tms_utime, tms_stime, tms_cutime, and tms_cstime fields of the tms structure

File size limit (see the ulimit(2) reference page)

Upon successful completion of the function call, the st_atime field of the file is marked for update.

The POSIX.1 standard does not specify the effect on the st_atime field when the function call fails but does find the file. Likewise, the HP implementation does not guarantee the outcome.

Under these circumstances, this field should not be used for further processing.

Guardian Attributes

The newly created OSS process retains the following Guardian attributes of the process that calls one of the exec set of functions:

Priority

Processor on which the process executes

Home terminal

Job ID

DEFINE mode switch

Process access ID (PAID), unless the S_ISUID mode bit of the new image file is set

Security group list

Job ancestor or GMOM

Unread system message index (PCBMCNT)

This attribute assignment is different from the assignment made when creating a new process with Guardian procedures.

Outstanding incoming and outgoing message limits

This attribute assignment is different from the assignment made when creating a new process with Guardian procedures.

2

30 Hewlett-Packard Company 527186-003

System Functions (e) execv(2)

Login, remote, and saveabend flags

File creation mask

The Guardian attributes of the new process differ from those of the calling process in the following ways:

Segments created or shared using Guardian procedure calls such as

SEGMENT_ALLOCATE_ are not inherited.

The program file is the file specified in the function call.

The library file is specified in the program file.

The new process does not inherit the caller’s extended swap file (if any). For a G-series

TNS process or an accelerated process, the extended data segment is managed by the

Kernel Managed Storage Facility (KMSF).

The process name for the new process is system-generated if the RUNNAMED option is set in the program file. Otherwise the process is unnamed.

The size of the data segment of the new process is set in the program file.

The remote login flag (PCBREMID) is set to off if the program file has had its S_ISUID mode bit set. Otherwise, the remote login flag is set the same as for the caller.

The size of the extended data segment of the new process is set in the program file.

The DEFINEs inherited by the new process depend on the setting of DEFINE mode in the caller. If DEFINE mode in the caller is ON, all the caller’s DEFINEs are inherited.

If DEFINE mode is OFF, no DEFINEs are inherited.

The process identification number (PIN) of the new process is unrelated to that of the calling process. The PIN of the new process is unrestricted if both of the following are true:

— The HIGHPIN flag is set in the program file and any user library file.

— The PIN of the calling process was unrestricted.

If the PIN of the new process is restricted, then the PIN is in the range 0 through 254.

The creator access ID (CAID) is set to the process access ID (PAID) of the calling process.

The PAID depends on whether the S_ISUID mode bit of the image file is set. If so, the

PAID is based on the file owner ID. If not, the PAID is the same as for the caller. (The

S_ISUID mode bit of the image file has no effect on the security group list.)

The MOM field for the new process depends on whether the calling process is named. If so, the MOM field for the new process is set to the caller’s ANCESTOR field. Otherwise, the MOM field for the new process is set to the caller’s MOM field.

System debugger selection for the new process is based on Inspect mode.

Code breakpoints and memory breakpoints are not inherited.

For detailed information about Guardian process attributes, see the PROCESS_LAUNCH_ procedure in the Guardian Procedure Calls Reference Manual.

527186-003 Hewlett-Packard Company 2

31

execv(2) OSS System Calls Reference Manual

Use From the Guardian Environment

If called from a Guardian process, the function call fails and errno is set to [ENOTOSS].

RETURN VALUES

If the execv( ) function returns to the calling process image, an error has occurred; the return value is -1, and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the function sets errno to the corresponding value. For any of these error conditions, file descriptors marked close-on-exec are not closed, signals set to be caught are not set to the default action, and none of the following are changed:

The argv[ ] array of pointers

The elements pointed to by this array

The value of the global variable environ

The pointers contained within the global variable environ

The elements pointed to by environ pointers

The effective user ID of the current process

The effective group ID of the current process

[E2BIG]

[EACCES]

The number of bytes used by the new process image’s argument list and environment list is greater than the system-imposed limit. The limit can be obtained by calling the sysconf(_SC_ARG_MAX) function.

One of the following conditions exists:

Search permission is denied for the directory components of the pathname prefix to the process image file.

The new process image file, any library file, or script file denies execution permission.

The new process image file is not a regular file.

[EAGAIN]

[EFAULT]

[EINVAL]

[ELOOP]

System resources such as disk space, process control block (PCB) space, MAP-

POOL space, stack space, or PFS space are temporarily inadequate.

An input address parameter is outside valid bounds limits.

The new process image file is a binary executable file with invalid attributes.

Too many symbolic links were encountered in pathname resolution.

[EMFILE] The maximum number of files is open. The process attempted to open more than the maximum number of file descriptors allowed for the process. The process file segment (PFS) of the new process might be smaller than that of the calling process.

[ENAMETOOLONG]

One of the following is too long:

The pathname pointed to by the path parameter

2

32 Hewlett-Packard Company 527186-003

System Functions (e) execv(2)

A component of the pathname pointed to by the path parameter

The intermediate result of pathname resolution when a symbolic link is part of the pathname pointed to by the path parameter

The pathconf( ) function can be called to obtain the applicable limits.

[ENODEV] The system cannot find the device containing the fileset containing the process image file.

[ENOENT] One of the following conditions exists:

One or more components of the new process image file’s pathname do not exist.

The path parameter points to an empty string.

[ENOEXEC] The new process image file has the appropriate access permissions, but it is neither in the correct binary executable format nor a valid executable text file.

[ENOMEM] Required resources are not available. Subsequent calls to the same function will not succeed for the same reason.

Possible causes of this error include insufficient primary memory (stack, globals, or heap) for the new process.

[ENOTDIR] A component of the path prefix of the new process image file is not a directory.

[ENOTOSS] The calling process is not an OSS process. A function in the exec set of functions cannot be called from the Guardian environment.

[ETXTBSY] The new process image file is currently open for writing by a process.

[EUNKNOWN]

Unknown error. An unrecognized or very obscure error occurred. If this error occurs, follow site-defined procedures for reporting software problems to

HP.

RELATED INFORMATION

Commands: eld(1), ld(1), nld(1).

Functions: alarm(3), _exit(2), execl(2), execle(2), execlp(2), execve(2), execvp(2), fcntl(2),

fork(2), getenv(3), putenv(3), semget(2), sigaction(2), system(3), tdm_execve(2),

tdm_execvep(2), tdm_fork(2), tdm_spawn(2), tdm_spawnp(2), times(3), ulimit(3), umask(2).

Miscellaneous: environ(5).

STANDARDS CONFORMANCE

The POSIX standards leave some features to the implementing vendor to define. The following features are affected in the HP implementation:

Guardian attributes are associated with the new OSS process. See Guardian Attributes under DESCRIPTION.

The contents of the st_atime field following a failed function call in which the file was found should not be depended upon for further processing.

The use of *env[ ] as a parameter in the call to main( ) is an HP extension.

527186-003 Hewlett-Packard Company 2

33

execv(2) OSS System Calls Reference Manual

The following are HP extensions to the XPG4 Version 2 specification:

Text files containing the #! interpreter_name [optional_string] header line can execute.

The [EINVAL], [ENODEV], [ENOTOSS], and [EUNKNOWN] error values are an

HP extension.

2

34 Hewlett-Packard Company 527186-003

System Functions (e) execve(2)

NAME

execve - Executes a file using a pathname, an argv array, and an envp array

LIBRARY

G-series native OSS processes: /G/system/sysnn/zossksrl

H-series OSS processes: /G/system/zdllnnn/zosskdll

SYNOPSIS

#include <unistd.h> extern char

∗∗∗∗

environ; int execve( const char

∗∗

path,

char

∗∗

const argv[ ],

char

∗∗

const envp[ ]);

PARAMETERS

**environ

path

argv[ ]

envp[ ]

Points to an array of character pointers to environment strings. The environment strings define the OSS environment for the calling process. The environ array is terminated by a null pointer.

When the new process is created, the corresponding **environ array is not initialized for it with the content of the **environ array of the calling process.

Instead, the envp[ ] array is written into the **environ array of the new process when the execve( ) function call is processed.

The **environ array of the new process is also passed as the env[ ] array in the call to the main( ) function of the new process. Refer to Entering the New Pro-

cess later in this reference page.

Points to a null-terminated string containing a pathname that identifies the new process image file. The pathname is absolute if it starts with a slash (/) character.

Otherwise, the pathname is relative and is resolved by prefixing the current working directory.

If the final component of the path parameter names a symbolic link, the link is traversed and pathname resolution continues.

Specifies an array of character pointers to null-terminated strings containing arguments to be passed to the main function of the new program. argv[0] should point to the null-terminated string containing the filename of the new process image. The last member of this array must be a null pointer.

These strings constitute the argument list available to the new process image.

Specifies an array of character pointers to null-terminated strings that describe the environment for the new process. The last member of this array must be a null pointer.

DESCRIPTION

The execve( ) function is one of the exec set of functions. The exec set of functions replace the current process image with a new process image. The new image is constructed from a regular executable file, called a new process image file. The new process image file is formatted as an executable text or binary file in one of the formats recognized by the exec set of functions.

527186-003 Hewlett-Packard Company 2

35

execve(2) OSS System Calls Reference Manual

A successful execve( ) function call does not return, because the calling process image is overlaid by the new process image.

Entering the New Process

When a program is executed as a result of a call to a function in the exec set of functions, it is entered as a function call as follows:

int main(

int argc,

char

∗∗

argv[ ],

char

∗∗

env[ ]);

Here, the argc parameter is the argument count, the argv[ ] parameter is an array of character pointers to the arguments themselves, and env[ ] is a pointer to a character array listing the environment variables. The argv[ ] array is terminated by a null pointer. The null pointer is not counted in argc.

The arguments specified by a program with one of the exec set of functions are passed on to the new process image in the corresponding arguments to the main( ) function.

The env[ ] parameter for the main function is an HP extension and is not the preferred method of obtaining the environment variables for the new process. Use of the **environ array is the preferred method.

Passing the Arguments and the Environment

The number of bytes available for the new process’s combined argument and environment lists has a system-imposed limit. This limit, which includes the pointers and the null terminators on the strings, is available by calling the sysconf(_SC_ARG_MAX) function.

Executing a Binary File

If the file specified in the function call is a binary executable file, the function loads the file directly.

Executing a Text File

If the file specified in the function call is not a binary executable file, the function examines the file to determine whether it is an executable text file. The function checks for a header line in the following format:

#! interpreter_name [optional_string]

The #! notation identifies the file as an executable text file. The new process image filename is constructed from the process image filename in the interpreter_name string, treating it like the

path parameter. The arguments passed to the new process are modified as follows:

The argv[0] parameter is set to the name of the interpreter.

If the optional_string portion is present, argv[1] is set to optional_string.

The next element of argv[ ] is set to the original value of path.

The remaining elements of argv[ ] are set to the original elements of argv[ ], starting with

argv[1].

The original argv[0] is discarded.

The S_ISUID and S_ISGID mode bits of an executable text file are honored. Those bits of the

interpreter_name command interpreter are ignored.

2

36 Hewlett-Packard Company 527186-003

System Functions (e) execve(2)

When the File Is Invalid

If the process image file is not a valid executable object, or if the text file does not contain the header line, the execve( ) function call fails and errno is set to the value of [ENOEXEC].

Open Files

File descriptors open in the calling process image remain open in the new process image, except for those:

Whose close-on-exec flag FD_CLOEXEC is set (see the fcntl(2) reference page)

Opened using a Guardian function or procedure call

If the process file segment of the new process image is smaller than the process file segment of the calling process image and if the calling process image has a large number of file descriptors open, then the system might not be able to propagate all the open file descriptors to the new process image. When this situation occurs, the function call fails and errno is set to the value of

[EMFILE].

For those file descriptors that remain open, all attributes of the open file descriptor, including file locks, remain unchanged. All directory streams are closed.

Shared Memory

Any attached shared memory segments are detached by a successful call to a function in the exec set of functions. Refer to the shmat(2) reference page for additional information about shared memory segment use.

Semaphores

Semaphore set IDs attached to a calling process are also attached to the new process. The new process also inherits the adjust-on-exit (semadj) values of the calling process.

Refer to the semget(2) reference page for additional information about semaphore use.

Signals

Signals set to:

The default action (SIG_DFL) in the calling process image are set to the default action in the new process image.

Be ignored (SIG_IGN) by the calling process image are set to be ignored by the new process image.

Cause abnormal termination (SIG_ABORT) in the calling process image are set to that | action in the new process image.

Cause entry into the debugger (SIG_DEBUG) in the calling process image are set to that | action in the new process image.

Be caught by the calling process image are set to the default action in the new process image.

See the signal(4) reference page either online or in the Open System Services System Calls Refer- |

ence Manual.

User ID and Group ID

If the set-user-ID mode bit of the new process image file is set (see the chmod(2) reference page), the effective user ID of the new process image is set to the owner ID of the new process image file. Similarly, if the set-group-ID mode bit of the new process image file is set, the effective group ID of the new process image is set to the group ID of the new process image file.

The real user ID, real group ID, and supplementary group IDs of the new process image remain the same as those of the calling process image. The effective user ID and effective group ID of

527186-003 Hewlett-Packard Company 2

37

execve(2) OSS System Calls Reference Manual

the new process image are saved (as the saved-set-user ID and the saved-set-group ID) for use by the setuid( ) function.

The _POSIX_SAVED_IDS flag is defined TRUE.

OSS Attributes

The following OSS attributes of the calling process image are unchanged after successful completion of any of the exec set of functions:

OSS process ID (PID)

Parent process ID

Process group ID

Session membership

Real user ID

Real group ID

Supplementary group IDs

The time left until an alarm clock signal is posted (see the alarm(3) reference page)

Current working directory

Root directory

File mode creation mask (see the umask(2) reference page)

Process signal mask (see the sigprocmask(2) reference page)

Pending signals (see the sigpending(2) reference page)

The tms_utime, tms_stime, tms_cutime, and tms_cstime fields of the tms structure

File size limit (see the ulimit(2) reference page)

Upon successful completion of the function call, the st_atime field of the file is marked for update.

The POSIX.1 standard does not specify the effect on the st_atime field when the function call fails but does find the file. Likewise, the HP implementation does not guarantee the outcome.

Under these circumstances, this field should not be used for further processing.

Guardian Attributes

The newly created OSS process retains the following Guardian attributes of the process that calls one of the exec set of functions:

Priority

Processor on which the process executes

Home terminal

Job ID

DEFINE mode switch

Process access ID (PAID), unless the S_ISUID mode bit of the new image file is set

2

38 Hewlett-Packard Company 527186-003

System Functions (e) execve(2)

Security group list

Job ancestor or GMOM

Unread system message index (PCBMCNT)

This attribute assignment is different from the assignment made when creating a new process with Guardian procedures.

Outstanding incoming and outgoing message limits

This attribute assignment is different from the assignment made when creating a new process with Guardian procedures.

Login, remote, and saveabend flags

File creation mask

The Guardian attributes of the new process differ from those of the calling process in the following ways:

Segments created or shared using Guardian procedure calls such as

SEGMENT_ALLOCATE_ are not inherited.

The program file is the file specified in the function call.

The library file is specified in the program file.

The new process does not inherit the caller’s extended swap file (if any). For a G-series

TNS process or an accelerated process, the extended data segment is managed by the

Kernel Managed Storage Facility (KMSF).

The process name for the new process is system-generated if the RUNNAMED option is set in the program file. Otherwise the process is unnamed.

The size of the data segment of the new process is set in the program file.

The remote login flag (PCBREMID) is set to off if the program file has had its S_ISUID mode bit set. Otherwise, the remote login flag is set the same as for the caller.

The size of the extended data segment of the new process is set in the program file.

The DEFINEs inherited by the new process depend on the setting of DEFINE mode in the caller. If DEFINE mode in the caller is ON, all the caller’s DEFINEs are inherited.

If DEFINE mode is OFF, no DEFINEs are inherited.

The process identification number (PIN) of the new process is unrelated to that of the calling process. The PIN of the new process is unrestricted if both of the following are true:

— The HIGHPIN flag is set in the program file and any user library file.

— The PIN of the calling process was unrestricted.

If the PIN of the new process is restricted, then the PIN is in the range 0 through 254.

The creator access ID (CAID) is set to the process access ID (PAID) of the calling process.

527186-003 Hewlett-Packard Company 2

39

execve(2) OSS System Calls Reference Manual

The PAID depends on whether the S_ISUID mode bit of the image file is set. If so, the

PAID is based on the file owner ID. If not, the PAID is the same as for the caller. (The

S_ISUID mode bit of the image file has no effect on the security group list.)

The MOM field for the new process depends on whether the calling process is named. If so, the MOM field for the new process is set to the caller’s ANCESTOR field. Otherwise, the MOM field for the new process is set to the caller’s MOM field.

System debugger selection for the new process is based on Inspect mode.

Code breakpoints and memory breakpoints are not inherited.

For detailed information about Guardian process attributes, see the PROCESS_LAUNCH_ procedure in the Guardian Procedure Calls Reference Manual.

Use From the Guardian Environment

If called from a Guardian process, the function call fails and errno is set to [ENOTOSS].

RETURN VALUES

If the execve( ) function returns to the calling process image, an error has occurred; the return value is -1, and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the function sets errno to the corresponding value. For any of these error conditions, file descriptors marked close-on-exec are not closed, signals set to be caught are not set to the default action, and none of the following are changed:

The argv[ ] array of pointers

The envp[ ] array of pointers

The elements pointed to by these arrays

The effective user ID of the current process

The effective group ID of the current process

[E2BIG]

[EACCES]

The number of bytes used by the new process image’s argument list and environment list is greater than the system-imposed limit. The limit can be obtained by calling the sysconf(_SC_ARG_MAX) function.

One of the following conditions exists:

Search permission is denied for the directory components of the pathname prefix to the process image file.

The new process image file, any library file, or script file denies execution permission.

The new process image file is not a regular file.

[EAGAIN]

[EFAULT]

System resources such as disk space, process control block (PCB) space, MAP-

POOL space, stack space, or PFS space are temporarily inadequate.

An input address parameter is outside valid bounds limits.

2

40 Hewlett-Packard Company 527186-003

System Functions (e) execve(2)

[EINVAL]

[ELOOP]

[EMFILE]

The new process image file is a binary executable file with invalid attributes.

Too many symbolic links were encountered in pathname resolution.

The maximum number of files is open. The process attempted to open more than the maximum number of file descriptors allowed for the process. The process file segment (PFS) of the new process might be smaller than that of the calling process.

[ENAMETOOLONG]

One of the following is too long:

The pathname pointed to by the path parameter

A component of the pathname pointed to by the path parameter

The intermediate result of pathname resolution when a symbolic link is part of the pathname pointed to by the path parameter

The pathconf( ) function can be called to obtain the applicable limits.

[ENODEV] The system cannot find the device containing the fileset containing the process image file.

[ENOENT] One of the following conditions exists:

One or more components of the new process image file’s pathname do not exist.

The path parameter points to an empty string.

[ENOEXEC] The new process image file has the appropriate access permissions, but it is neither in the correct binary executable format nor a valid executable text file.

[ENOMEM] Required resources are not available. Subsequent calls to the same function will not succeed for the same reason.

Possible causes of this error include insufficient primary memory (stack, globals, or heap) for the new process.

[ENOTDIR] A component of the path prefix of the new process image file is not a directory.

[ENOTOSS] The calling process is not an OSS process. A function in the exec set of functions cannot be called from the Guardian environment.

[ETXTBSY] The new process image file is currently open for writing by a process.

[EUNKNOWN]

Unknown error. An unrecognized or very obscure error occurred. If this error occurs, follow site-defined procedures for reporting software problems to

HP.

RELATED INFORMATION

Commands: eld(1), ld(1), nld(1).

Functions: alarm(3), _exit(2), execl(2), execle(2), execlp(2), execv(2), execvp(2), fcntl(2),

fork(2), getenv(3), putenv(3), semget(2), sigaction(2), system(3), tdm_execve(2),

tdm_execvep(2), tdm_fork(2), tdm_spawn(2), tdm_spawnp(2), times(3), ulimit(3), umask(2).

Miscellaneous: environ(5).

527186-003 Hewlett-Packard Company 2

41

execve(2) OSS System Calls Reference Manual

STANDARDS CONFORMANCE

The POSIX standards leave some features to the implementing vendor to define. The following features are affected in the HP implementation:

Guardian attributes are associated with the new OSS process. See Guardian Attributes under DESCRIPTION.

The contents of the st_atime field following a failed function call in which the file was found should not be depended upon for further processing.

The use of *env[ ] as a parameter in the call to main( ) is an HP extension.

The following are HP extensions to the XPG4 Version 2 specification:

Text files containing the #! interpreter_name [optional_string] header line can execute.

The [EINVAL], [ENODEV], [ENOTOSS], and [EUNKNOWN] error values are an

HP extension.

2

42 Hewlett-Packard Company 527186-003

System Functions (e) execvp(2)

NAME

execvp - Executes a file using a filename, an argv array, and **environ

LIBRARY

G-series native OSS processes: /G/system/sysnn/zossksrl

H-series OSS processes: /G/system/zdllnnn/zosskdll

SYNOPSIS

#include <unistd.h> extern char

∗∗∗∗

environ; int execvp( const char

∗∗

file,

char

∗∗

const argv[ ]);

PARAMETERS

**environ

file

Points to an array of character pointers to environment strings. The environment strings define the OSS environment for the new process. The environ array is terminated by a null pointer.

The **environ array of the new process is also passed as the env[ ] array in the call to the main( ) function of the new process. Refer to Entering the New Pro-

cess later in this reference page.

Identifies the new process image file. If this parameter

Starts with a slash (/) character, then it contains the absolute pathname.

Does not start with a slash but does contain a slash, then the pathname resolves relative to the current working directory.

Contains no slash, the system searches the directories listed in the PATH environment variable for the file and prefixes the directory in which it is found.

argv[ ] Specifies an array of character pointers to null-terminated strings containing arguments to be passed to the main function of the new program. argv[0] should point to the null-terminated string containing the filename of the new process image. The last member of this array must be a null pointer.

These strings constitute the argument list available to the new process image.

DESCRIPTION

The execvp( ) function is one of the set of exec functions. The exec set of functions replace the current process image with a new process image. The new image is constructed from a regular executable file, called a new process image file. The new process image file is formatted as an executable text or binary file in one of the formats recognized by the exec set of functions.

A successful execvp( ) function call does not return, because the calling process image is overlaid by the new process image.

527186-003 Hewlett-Packard Company 2

43

execvp(2) OSS System Calls Reference Manual

Entering the New Process

When a program is executed as a result of a call to a function in the exec set of functions, it is entered as a function call as follows:

int main(

int argc,

char

∗∗

argv[ ],

char

∗∗

env[ ]);

Here, the argc parameter is the argument count, the argv[ ] parameter is an array of character pointers to the arguments themselves, and env[ ] is a pointer to a character array listing the environment variables. The argv[ ] array is terminated by a null pointer. The null pointer is not counted in argc.

The arguments specified by a program with one of the exec set of functions are passed on to the new process image in the corresponding arguments to the main( ) function.

The env[ ] parameter for the main function is an HP extension and is not the preferred method of obtaining the environment variables for the new process. Use of the **environ array is the preferred method.

Passing the Arguments and the Environment

The number of bytes available for the new process’s combined argument and environment lists has a system-imposed limit. This limit, which includes the pointers and the null terminators on the strings, is available by calling the sysconf(_SC_ARG_MAX) function.

Executing a Binary File

If the file specified in the function call is a binary executable file, the function loads the file directly.

Executing a Text File

If the file specified in the function call is not a binary executable file, the function examines the file to determine whether it is an executable text file. The function checks for a header line in the following format:

#! interpreter_name [optional_string]

The #! notation identifies the file as an executable text file. The new process image filename is constructed from the process image filename in the interpreter_name string, treating it like the

path parameter. The arguments passed to the new process are modified as follows:

The argv[0] parameter is set to the name of the interpreter.

If the optional_string portion is present, argv[1] is set to optional_string.

The next element of argv[ ] is set to the original value of file.

The remaining elements of argv[ ] are set to the original elements of argv[ ], starting with

argv[1].

The original argv[0] is discarded.

The S_ISUID and S_ISGID mode bits of an executable text file are honored. Those bits of the

interpreter_name command interpreter are ignored.

When the File Is Invalid

If the process image file is not a valid executable object, or if the text file does not contain the header line, the execvp( ) function invokes the /bin/sh command interpreter as the new process image and pass the following arguments to it:

2

44 Hewlett-Packard Company 527186-003

System Functions (e) execvp(2)

argv[0] is set to the string "sh".

argv[1] is set to the original value of the file parameter.

The remaining elements of argv[ ] are set to the original elements of argv[ ], starting with

argv[1].

The original value of argv[0] is discarded.

Open Files

File descriptors open in the calling process image remain open in the new process image, except for those:

Whose close-on-exec flag FD_CLOEXEC is set (see the fcntl(2) reference page)

Opened using a Guardian function or procedure call

If the process file segment of the new process image is smaller than the process file segment of the calling process image and if the calling process image has a large number of file descriptors open, then the system might not be able to propagate all the open file descriptors to the new process image. When this situation occurs, the function call fails and errno is set to the value of

[EMFILE].

For those file descriptors that remain open, all attributes of the open file descriptor, including file locks, remain unchanged. All directory streams are closed.

Shared Memory

Any attached shared memory segments are detached by a successful call to a function in the exec set of functions. Refer to the shmat(2) reference page for additional information about shared memory segment use.

Semaphores

Semaphore set IDs attached to a calling process are also attached to the new process. The new process also inherits the adjust-on-exit (semadj) values of the calling process.

Refer to the semget(2) reference page for additional information about semaphore use.

Signals

Signals set to:

The default action (SIG_DFL) in the calling process image are set to the default action in the new process image.

Be ignored (SIG_IGN) by the calling process image are set to be ignored by the new process image.

Cause abnormal termination (SIG_ABORT) in the calling process image are set to that | action in the new process image.

Cause entry into the debugger (SIG_DEBUG) in the calling process image are set to that | action in the new process image.

Be caught by the calling process image are set to the default action in the new process image.

See the signal(4) reference page either online or in the Open System Services System Calls Refer- |

ence Manual.

527186-003 Hewlett-Packard Company 2

45

execvp(2) OSS System Calls Reference Manual

User ID and Group ID

If the set-user-ID mode bit of the new process image file is set (see the chmod(2) reference page), the effective user ID of the new process image is set to the owner ID of the new process image file. Similarly, if the set-group-ID mode bit of the new process image file is set, the effective group ID of the new process image is set to the group ID of the new process image file.

The real user ID, real group ID, and supplementary group IDs of the new process image remain the same as those of the calling process image. The effective user ID and effective group ID of the new process image are saved (as the saved-set-user ID and the saved-set-group ID) for use by the setuid( ) function.

The _POSIX_SAVED_IDS flag is defined TRUE.

OSS Attributes

The following OSS attributes of the calling process image are unchanged after successful completion of any of the exec set of functions:

OSS process ID (PID)

Parent process ID

Process group ID

Session membership

Real user ID

Real group ID

Supplementary group IDs

The time left until an alarm clock signal is posted (see the alarm(3) reference page)

Current working directory

Root directory

File mode creation mask (see the umask(2) reference page)

Process signal mask (see the sigprocmask(2) reference page)

Pending signals (see the sigpending(2) reference page)

The tms_utime, tms_stime, tms_cutime, and tms_cstime fields of the tms structure

File size limit (see the ulimit(2) reference page)

Upon successful completion of the function call, the st_atime field of the file is marked for update.

The POSIX.1 standard does not specify the effect on the st_atime field when the function call fails but does find the file. Likewise, the HP implementation does not guarantee the outcome.

Under these circumstances, this field should not be used for further processing.

Guardian Attributes

The newly created OSS process retains the following Guardian attributes of the process that calls one of the exec set of functions:

Priority

2

46 Hewlett-Packard Company 527186-003

System Functions (e) execvp(2)

Processor on which the process executes

Home terminal

Job ID

DEFINE mode switch

Process access ID (PAID), unless the S_ISUID mode bit of the new image file is set

Security group list

Job ancestor or GMOM

Unread system message index (PCBMCNT)

This attribute assignment is different from the assignment made when creating a new process with Guardian procedures.

Outstanding incoming and outgoing message limits

This attribute assignment is different from the assignment made when creating a new process with Guardian procedures.

Login, remote, and saveabend flags

File creation mask

The Guardian attributes of the new process differ from those of the calling process in the following ways:

Segments created or shared using Guardian procedure calls such as

SEGMENT_ALLOCATE_ are not inherited.

The program file is the file specified in the function call.

The library file is specified in the program file.

The new process does not inherit the caller’s extended swap file (if any). For a G-series

TNS process or an accelerated process, the extended data segment is managed by the

Kernel Managed Storage Facility (KMSF).

The process name for the new process is system-generated if the RUNNAMED option is set in the program file. Otherwise the process is unnamed.

The size of the data segment of the new process is set in the program file.

The remote login flag (PCBREMID) is set to off if the program file has had its S_ISUID mode bit set. Otherwise, the remote login flag is set the same as for the caller.

The size of the extended data segment of the new process is set in the program file.

The DEFINEs inherited by the new process depend on the setting of DEFINE mode in the caller. If DEFINE mode in the caller is ON, all the caller’s DEFINEs are inherited.

If DEFINE mode is OFF, no DEFINEs are inherited.

The process identification number (PIN) of the new process is unrelated to that of the calling process. The PIN of the new process is unrestricted if both of the following are true:

— The HIGHPIN flag is set in the program file and any user library file.

527186-003 Hewlett-Packard Company 2

47

execvp(2) OSS System Calls Reference Manual

— The PIN of the calling process was unrestricted.

If the PIN of the new process is restricted, then the PIN is in the range 0 through 254.

The creator access ID (CAID) is set to the process access ID (PAID) of the calling process.

The PAID depends on whether the S_ISUID mode bit of the image file is set. If so, the

PAID is based on the file owner ID. If not, the PAID is the same as for the caller. (The

S_ISUID mode bit of the image file has no effect on the security group list.)

The MOM field for the new process depends on whether the calling process is named. If so, the MOM field for the new process is set to the caller’s ANCESTOR field. Otherwise, the MOM field for the new process is set to the caller’s MOM field.

System debugger selection for the new process is based on Inspect mode.

Code breakpoints and memory breakpoints are not inherited.

For detailed information about Guardian process attributes, see the PROCESS_LAUNCH_ procedure in the Guardian Procedure Calls Reference Manual.

Use From the Guardian Environment

If called from a Guardian process, the function call fails and errno is set to [ENOTOSS].

RETURN VALUES

If the execvp( ) function returns to the calling process image, an error has occurred; the return value is -1, and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the function sets errno to the corresponding value. For any of these error conditions, file descriptors marked close-on-exec are not closed, signals set to be caught are not set to the default action, and none of the following are changed:

The argv[ ] array of pointers

The elements pointed to by this array

The value of the global variable environ

The pointers contained within the global variable environ

The elements pointed to by environ pointers

The effective user ID of the current process

The effective group ID of the current process

[E2BIG]

[EACCES]

The number of bytes used by the new process image’s argument list and environment list is greater than the system-imposed limit. The limit can be obtained by calling the sysconf(_SC_ARG_MAX) function.

One of the following conditions exists:

Search permission is denied for the directory components of the pathname prefix to the process image file.

2

48 Hewlett-Packard Company 527186-003

System Functions (e) execvp(2)

The new process image file, any library file, or script file denies execution permission.

The new process image file is not a regular file.

[EAGAIN]

[EFAULT]

[EINVAL]

[ELOOP]

[EMFILE]

System resources such as disk space, process control block (PCB) space, MAP-

POOL space, stack space, or PFS space are temporarily inadequate.

An input address parameter is outside valid bounds limits.

The new process image file is a binary executable file with invalid attributes.

Too many symbolic links were encountered in pathname resolution.

The maximum number of files is open. The process attempted to open more than the maximum number of file descriptors allowed for the process. The process file segment (PFS) of the new process might be smaller than that of the calling process.

[ENAMETOOLONG]

One of the following is too long:

The intermediate result of pathname resolution when a symbolic link is part of the value specified by the file parameter

The pathconf( ) function can be called to obtain the applicable limits.

[ENODEV] The system cannot find the device containing the fileset containing the process image file.

[ENOENT] The file parameter points to an empty string.

[ENOEXEC] The new process image file has the appropriate access permissions, but it is neither in the correct binary executable format nor a valid executable text file. The

/bin/sh command interpreter could not be invoked as a substitute.

[ENOMEM] Required resources are not available. Subsequent calls to the same function will not succeed for the same reason.

Possible causes of this error include insufficient primary memory (stack, globals, or heap) for the new process.

[ENOTDIR] A component of the path prefix of the new process image file is not a directory.

[ENOTOSS] The calling process is not an OSS process. A function in the exec set of functions cannot be called from the Guardian environment.

[ETXTBSY] The new process image file is currently open for writing by a process.

[EUNKNOWN]

Unknown error. An unrecognized or very obscure error occurred. If this error occurs, follow site-defined procedures for reporting software problems to

HP.

RELATED INFORMATION

Commands: eld(1), ld(1), nld(1).

Functions: alarm(3), _exit(2), execl(2), execle(2), execlp(2), execv(2), execve(2), fcntl(2),

fork(2), getenv(3), putenv(3), semget(2), sigaction(2), system(3), tdm_execve(2),

tdm_execvep(2), tdm_fork(2), tdm_spawn(2), tdm_spawnp(2), times(3), ulimit(3), umask(2).

527186-003 Hewlett-Packard Company 2

49

execvp(2) OSS System Calls Reference Manual

Miscellaneous: environ(5).

STANDARDS CONFORMANCE

The POSIX standards leave some features to the implementing vendor to define. The following features are affected in the HP implementation:

Guardian attributes are associated with the new OSS process. See Guardian Attributes under DESCRIPTION.

[ENOENT] is returned in errno if the environment variable PATH is not defined when the execvp( ) function is called.

The contents of the st_atime field following a failed function call in which the file was found should not be depended upon for further processing.

The use of *env[ ] as a parameter in the call to main( ) is an HP extension.

The following are HP extensions to the XPG4 Version 2 specification:

Text files containing the #! interpreter_name [optional_string] header line can execute.

The [EINVAL], [ENODEV], [ENOTOSS], and [EUNKNOWN] error values are an

HP extension.

2

50 Hewlett-Packard Company 527186-003

System Functions (e) _exit(2)

NAME

_exit - Terminates a process

LIBRARY

G-series native Guardian processes: system library

G-series native OSS processes: system library

H-series native Guardian processes: implicit libraries

H-series OSS processes: implicit libraries

SYNOPSIS

#include <unistd.h> void _exit(

int status);

PARAMETERS

status

Indicates the status of the process.

DESCRIPTION

The _exit( ) function terminates the calling process and causes the following to occur:

All the file descriptors and directory streams that are open in the calling process are closed.

All shared memory segments attached to the calling process are detached from it. The value of the shm_nattch field in the data structure associated with the shared memory identifier of each affected shared memory segment is decremented by 1. Refer to the

shmget(2) reference page for more information.

The semadj value established by the calling process for each semaphore is added to the

semval value for that semaphore. Refer to the semop(2) reference page for more information.

Terminating a process by exiting does not terminate its child processes. Instead, the parent process ID of all the calling process’s child processes and zombie child processes is set to 1.

If the parent process of the calling process is executing the wait( ) or waitpid( ) function, the parent is notified of the termination of the calling process and the low-order 8 bits

(that is, bits 24 through 31) of the status parameter are made available to it.

If the parent process is not executing the wait( ) or waitpid( ) function when the child process terminates, the parent can do so later and the child’s status will be returned to it at that time. Meanwhile, the child process is transformed into a zombie process, and its parent process is sent a SIGCHLD signal to notify it of the termination of a child process.

A zombie process is a process that occupies a slot in the process table but has no other space allocated to it either in user or kernel space. The process table slot that it occupies is partially overlaid with time-accounting information to be used by the times( ) function.

(See the sys/proc.h header file.)

A process remains a zombie process until its parent process issues a call to the wait( ) or

waitpid( ) function. At this time, the zombie process goes away and its process table entry is released.

If the process is a controlling process, a SIGHUP signal is sent to each process in the foreground process group of the controlling terminal belonging to the calling process.

The controlling terminal is dissociated from the session, allowing it to be acquired by a

527186-003 Hewlett-Packard Company 2

51

_exit(2) OSS System Calls Reference Manual

new controlling process.

If the exit of a process causes a process group to become orphaned, and if any member of the newly orphaned process group is stopped, then a SIGHUP signal followed by a

SIGCONT signal is sent to each member of the orphaned process group.

Locks set by the fcntl( ) function are removed.

Use From the Guardian Environment

The _exit( ) function can be called from any Guardian process as well as from OSS processes.

Guardian processes, however, have no OSS process ID (PID) and therefore have no wait considerations.

NOTES

Open System Services currently does not support Common-Usage C.

RETURN VALUES

The _exit( ) function does not return.

RELATED INFORMATION

Functions: atexit(3), close(2), exit(3), semop(2), shmget(2), sigaction(2), times(3), wait(2).

STANDARDS CONFORMANCE

The POSIX standards leave some features to the implementing vendor to define. The following features are affected in the HPimplementation:

Open System Services currently does not support Common-Usage C.

Child processes of a terminated process are assigned a parent process ID of 1.

2

52 Hewlett-Packard Company 527186-003

Section 3. System Functions (f - i)

This section contains reference pages for Open System Services (OSS) system function calls with names that begin with f through i. These reference pages reside in the cat2 directory and are sorted alphabetically by U.S. English conventions in this section.

527186-003 Hewlett-Packard Company 3

1

fcntl(2) OSS System Calls Reference Manual

NAME

fcntl - Controls open file descriptors

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/types.h>

/* optional except for POSIX.1 */

#include <unistd.h>

#include <fcntl.h>

/* optional except for POSIX.1 */

int fcntl(

int filedes,

int request

[ , int argument1 | , struct flock *argument2 ] );

PARAMETERS

filedes request argument1 argument2

Specifies an open file descriptor obtained from a successful call to the accept( ),

creat( ), dup( ), dup2( ), fcntl( ), open( ), pipe( ), socket( ), or socketpair( ) function

Specifies the operation to be performed

Specifies a variable that depends on the value of the request parameter

Specifies a variable that depends on the value of the request parameter

DESCRIPTION

The fcntl( ) function performs controlling operations on the open file specified by the filedes parameter.

Values for the request parameter are:

F_DUPFD

Returns a new file descriptor as listed:

Returns the lowest-numbered available file descriptor that is greater than or equal to the argument1 parameter

References the same open

Returns the same file pointer as the original file (that is, both file descriptors share one file pointer if the object is a file)

Returns the same access mode (read, write, or read/write)

Returns the same file status flags (that is, both file descriptors share the same file status flags)

Clears the close-on-exec flag (FD_CLOEXEC bit) associated with the new file descriptor so that the file remains open across calls to any function in the exec, tdm_exec, or tdm_spawn sets of functions

The value F_DUPFD is invalid for an OSSTTY or Telserv terminal device. If this value is used in a call that specifies such a device for the filedes parameter, the call fails and errno is set to [EINVAL].

3

2 Hewlett-Packard Company 527186-003

System Functions (f - i) fcntl(2)

F_GETFD

F_SETFD

F_GETFL

F_SETFL

Gets the value of the file descriptor flags, defined in the fcntl.h header file, that are associated with the value of the filedes parameter. File descriptor flags are associated with a single file descriptor and do not affect other file descriptors that refer to the same file. The argument1 parameter or argument2 parameter is ignored.

The value F_GETFD is invalid for an OSSTTY or Telserv terminal device. If this value is used in a call that specifies such a device for the filedes parameter, the call fails and errno is set to [EINVAL].

Sets the value of the file descriptor flags, defined in the fcntl.h header file, that are associated with the filedes parameter to the value of the argument1 parameter.

If the FD_CLOEXEC flag in the argument1 parameter is 0 (zero), the file remains open across calls to any function in the exec, tdm_exec, and

tdm_spawn sets of functions; otherwise, the file is closed on successful execution of the next function in an exec, tdm_exec, or tdm_spawn function set.

When the FD_CLOEXEC flag is set, no other flag can be set in the call.

The value F_SETFD is invalid for an OSSTTY or Telserv terminal device. If this value is used in a call that specifies such a device for the filedes parameter, the call fails and errno is set to [EINVAL].

Gets the file status flags and file access modes, defined in the fcntl.h header file, for the file referred to by the filedes parameter.

The file access modes can be extracted by using the mask O_ACCMODE on the return value. File status flags and file access modes are associated with the file descriptor and do not affect other file descriptors that refer to the same file with different open file descriptors.

The argument1 or argument2 parameter is ignored.

The O_APPEND, O_NONBLOCK, and O_SYNC flags are not returned as set if they were ignored in a previous call using F_SETFL.

Sets the file status flags O_APPEND, O_NONBLOCK, and O_SYNC for the file to which the filedes parameter refers, from the corresponding bits in the argu-

ment1 parameter. Some flags are ignored, depending on the file type, as listed:

Table 3

1. Ignored File Status Flags

Ignored file status flags

Directory O_APPEND, O_NONBLOCK,

O_SYNC

FIFO, pipe O_APPEND, O_SYNC

Character special file O_APPEND, O_SYNC

Regular file

Socket

O_NONBLOCK

None; however, see O_ASYNC note in text.

These file status flags are always accepted and ignored:

O_ACCMODE

O_CREAT

O_EXCL

O_TRUNC

527186-003 Hewlett-Packard Company 3

3

fcntl(2) OSS System Calls Reference Manual

3

4

The O_ASYNC flag is not supported for sockets. If the O_ASYNC flag is used with F_SETFL, the fcntl( ) call fails, and errno is set to [EINVAL].

The file access mode is not changed when F_SETFL is used.

F_GETOWN Gets the process ID or process group ID currently receiving the SIGURG signal for a socket. A process group ID is returned as a negative value. A positive value indicates the process ID.

The value F_GETOWN is invalid for these calls:

Guardian use of OSS sockets is not supported. If this value is used in a call from the Guardian environment, the call fails, and errno is set to

[ENOTOSS].

If this value is used in a call that specifies anything other than a socket for the filedes parameter, the call fails, and errno is set to [EINVAL].

F_SETOWN

Sets the process ID or process group ID to receive the SIGURG signal for a socket. A process group ID is specified by supplying it as a negative value in the

argument1 parameter; otherwise, the argument1 parameter is interpreted as a process ID.

The value F_SETOWN is invalid for these calls:

Guardian use of OSS sockets is not supported. If this value is used in a call from the Guardian environment, the call fails, and errno is set to

[ENOTOSS].

If this value is used in a call that specifies anything other than a socket for the filedes parameter, the call fails, and errno is set to [EINVAL].

These values listed for the request parameter are available for advisory record locking on regular files. Advisory record locking is supported only for regular files. If attempted on other files, the operation fails, and errno is set to [EINVAL].

F_GETLK

Gets the first lock that blocks the lock description pointed to by the argument2 parameter. The information retrieved overwrites the information passed to the

fcntl( ) function 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_SETLK

Sets or clears a file segment lock according to the lock description pointed to by the argument2 parameter. F_SETLK is used to establish shared locks

(F_RDLCK) or exclusive locks (F_WRLCK) and, additionally, to remove either type of lock (F_UNLCK). If a shared (read) or exclusive (write) lock cannot be set, the fcntl( ) function returns immediately with the value -1.

F_SETLKW

Same as F_SETLK except that, if a shared or exclusive lock is blocked by other locks, the process waits until it is unblocked. If a signal is received while fcntl( ) is waiting for a region, the function is interrupted, -1 is returned, and errno is set to [EINTR].

The O_NONBLOCK file status flag affects only operations against file descriptors derived from the same open( ) function.

When a shared lock is set on a segment of a file, other processes can set shared locks on that segment or a portion of it. A shared lock prevents any other process from setting an exclusive lock on any portion of the protected area. A request for a shared lock fails if the file descriptor is not

Hewlett-Packard Company 527186-003

System Functions (f - i) fcntl(2)

opened with read access.

An exclusive lock prevents any other process from setting a shared lock or an exclusive lock on any portion of the protected area. A request for an exclusive lock fails if the file descriptor was not opened with write access.

The flock structure describes the type (l_type field), starting offset (l_whence), relative offset

(l_start), size (l_len), and process ID (l_pid) of the segment of the file to be affected.

The value of l_whence is set to SEEK_SET, SEEK_CUR, or SEEK_END to indicate that the relative offset of l_start bytes is measured from the start of the file, from the current position, or from the end of the file, respectively. The value of l_len is the number of consecutive bytes to be locked. The l_len value can be negative (where the definition of type off_t permits negative values of l_len). The l_pid field is used only with F_GETLK to return the process ID of the process holding a blocking lock. After a successful F_GETLK request, the value of l_whence becomes SEEK_SET.

If l_len is positive, the area affected starts at l_start and ends at l_start + l_len - 1. If l_len is negative, the area affected starts at l_start + l_len and ends at l_start - 1. Lock lengths can be negative.

Locks can start and extend beyond the current end of a file, but they cannot be negative relative to the beginning of the file. If l_len is set to 0 (zero), a lock can be set to always extend to the largest possible value of the file offset for that file. If such a lock also has l_start set to 0 (zero) and l_whence is set to SEEK_SET, the whole file is locked.

Changing or unlocking a portion from the middle of a larger locked segment leaves a smaller segment at either end. Locking a segment that is already locked by the calling process causes the old lock type to be removed and the new lock type to take effect. All locks associated with a file for a given process are removed when a file descriptor for that file is closed by that process or when the process holding that file descriptor terminates. Locks are not inherited by a child process in a fork( ), tdm_fork( ), or tdm_spawn( )-type function.

RETURN VALUES

Upon successful completion, the value returned by the fcntl( ) function depends on the value of the request parameter, listed:

F_DUPFD

F_GETFD

F_GETFL

Returns a new file descriptor.

Returns the value of the file descriptor flags. The return value is not negative.

Returns the value of file status flags and access modes. The return value is not negative.

F_GETLK

Returns the value 0 (zero).

F_GETOWN Returns the process ID or process group ID of the socket receiving a SIGURG signal. A positive value is a process ID; a negative value is a process group ID.

F_SETFD

F_SETFL

Returns the value 0 (zero).

Returns the value 0 (zero).

F_SETLK

Returns the value 0 (zero).

F_SETLKW

Returns the value 0 (zero).

F_SETOWN

Returns the value 0 (zero).

If the fcntl( ) function fails, the value -1 is returned, and errno is set to indicate the error.

527186-003 Hewlett-Packard Company 3

5

fcntl(2) OSS System Calls Reference Manual

ERRORS

If any of these conditions occurs, the fcntl( ) function sets errno to the corresponding value:

[EAGAIN]

[EBADF]

The request parameter is F_SETLK, the type of lock (l_type) is shared

(F_RDLCK) or exclusive (F_WRLCK), and a segment of a file to be locked is already exclusive-locked by another process.

The request parameter is F_SETLK, the type of lock is exclusive, and some portion of a segment of a file to be locked is already shared-locked or exclusivelocked by another process.

One of these conditions exists:

The request parameter is F_SETLK or F_SETLKW, the type of lock is shared (F_RDLCK), and filedes is not a valid file descriptor open for reading.

The type of lock is exclusive (F_WRLCK), and filedes is not a valid file descriptor open for writing.

The filedes parameter is not a valid open file descriptor.

[ECONNRESET]

One of these conditions occurred:

The transport-provider process for this socket is no longer available.

The TCP/IP subsystem for this socket is no longer available.

The connection was forcibly closed by the peer socket.

The file descriptor specified by the filedes parameter can only be closed.

[EFAULT] The argument2 parameter is an invalid address.

[EINTR]

[EINVAL]

The request parameter is F_SETLKW, and the fcntl( ) function was interrupted by a signal that was caught.

One of these conditions exists:

The request parameter is F_DUPFD, and the argument1 parameter is negative or greater than or equal to the maximum number of opens permitted.

The request parameter is F_GETLK, F_SETLK, or F_SETLKW, and the data pointed to by argument2 is invalid, or filedes refers to a file that does not support locking.

The request parameter is F_GETOWN, and the filedes parameter does not specify a socket.

The request parameter is F_SETFD, and a flag in addition to

FD_CLOEXEC in the argument1 parameter is set. When the request parameter is F_SETFD and FD_CLOEXEC is set, no other flag can be set.

3

6 Hewlett-Packard Company 527186-003

System Functions (f - i) fcntl(2)

The request parameter is F_SETFL, and any file status flag other than

O_NONBLOCK, O_APPEND, O_CREAT, O_EXCL, O_SYNC, or

O_TRUNC is set. (Values set in the O_ACCMODE mask are ignored.)

The request parameter is F_SETOWN, and the filedes parameter does not specify a socket.

The call attempted to set an advisory record lock on a file that is not a regular file.

[EIO] An input or output error occurred. The device holding the file might be in the down state, or both processors that provide access to the device might have failed.

[EISGUARDIAN]

The value used for the filedes parameter is appropriate only in the Guardian environment.

[EMFILE] The request parameter is F_DUPFD and the maximum number of open file descriptors permitted are currently open in the calling process, or no file descriptors greater than or equal to argument1 are available.

[ENETDOWN]

The request parameter is F_SETLK, the filedes parameter specifies a file on a remote HP NonStop node, and communication with the remote node has been lost.

[ENOLCK] The request parameter is F_SETLK or F_SETLKW, and satisfying the lock or unlock request would result in the number of locked regions in the system exceeding a system-imposed limit.

[ENOTOSS] The filedes parameter specifies a socket, and the calling process is running in the

Guardian environment. The fcntl( ) function cannot be used on an OSS socket from the Guardian environment.

[EWRONGID] One of these conditions occurred:

The process attempted an operation through an operating system input/output process (such as a terminal server process) that has failed or is in the down state.

The processor for the disk process of the specified file failed during an input or output operation, and takeover by the backup process occurred.

The open file descriptor has migrated to a new processor, but the new processor lacks a resource or system process needed for using the file descriptor.

The file descriptor specified by the filedes parameter can only be closed.

For all other error conditions, errno is set to the appropriate Guardian file-system error number.

See the Guardian Procedure Errors and Messages Manual for more information about a specific

Guardian file-system error.

527186-003 Hewlett-Packard Company 3

7

fcntl(2) OSS System Calls Reference Manual

RELATED INFORMATION

Functions: creat(2), close(2), dup(2), dup2(2), exec(2), open(2), read(2), socket(2),

tdm_execve(2), tdm_execvep(2), write(2).

STANDARDS CONFORMANCE

The fcntl( ) function does not return the errno value [EDEADLK].

The fcntl( ) function does not support the O_ASYNC flag.

The POSIX standards leave some features to the implementing vendor to define. These features are affected in the HP implementation:

Advisory record locking is supported only for regular files. If attempted on other files, the operation fails, and errno is set to [EINVAL].

For record-locking operations, the l_len value can be negative (where the definition of

off_t permits negative values of l_len). If l_len is negative, the area affected by the lock starts at l_start + l_len and ends at l_start - 1.

HP extensions to the XPG4 Version 2 specification are:

The errno values [ECONNRESET], [EFAULT], [EIO], [EISGUARDIAN], [ENET-

DOWN], [ENOTOSS], and [EWRONGID] can be returned.

3

8 Hewlett-Packard Company 527186-003

System Functions (f - i) fork(2)

NAME

fork - Creates a new process

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/types.h>

/* optional except for POSIX.1 */

#include <unistd.h> pid_t fork(void);

DESCRIPTION

The fork( ) function creates a new OSS process. The created process is referred to as the child and the caller as the parent. The child process executes the same program file as the parent and retains many other Guardian attributes as well as OSS attributes of the parent.

The _POSIX_SAVED_IDS flag is defined TRUE. The saved-set-user-ID and saved-set-group-

ID fields of the parent process are therefore inherited by the child.

Use From the Guardian Environment

If called from a Guardian process, the actions of this function are undefined and errno is set to

[ENOTOSS].

OSS Attributes

The child process inherits the following OSS attributes from the parent process:

Environment

Close-on-exec flags

Signal handling settings

Saved-set-user-ID mode bit

Saved-set-group-ID mode bit

Process group ID

Current directory

Root directory

File mode creation mask

File size limit (see the ulimit(2) reference page)

Attached shared memory segments

Attached semaphore set IDs

The OSS attributes of the child process differ from those of the parent process in the following ways:

The child process has a unique OSS process ID (PID) and does not match any active process group ID.

The parent process ID of the child process matches the PID of the parent.

527186-003 Hewlett-Packard Company 3

9

fork(2) OSS System Calls Reference Manual

The child process has its own copy of the parent process’s file descriptors. However, each of the child’s file descriptors shares a common file pointer with the corresponding file descriptor of the parent process.

The child process does not inherit any file open created by a Guardian function or procedure call.

The child process does not inherit file locks.

The child process’s tms_utime, tms_stime, tms_cutime, and tms_cstime values are set to 0 (zero).

Any pending alarms are cleared in the child process.

Any signals pending for the parent process are not inherited by the child process.

Any adjust-on-exit (semadj) values of the parent process are cleared in the child process.

The child process shares directory streams with the parent. They share the same block of directory entries. When reading an entry, the buffer pointer is advanced by one entry.

From the perspective of either process, an entry might be skipped.

If both processes call the readdir( ) function for a shared stream, the results are undefined. After such a call by both functions, another call to the readdir( ) function by either process has undefined results.

Guardian Attributes

The child process inherits the following Guardian attributes from the parent process:

Program file

Any library files

The size and contents of any instance data segments for native libraries

Priority (the child process inherits the parent’s current priority)

Processor on which the process executes

Home terminal

For G-series TNS or accelerated processes, the size and contents of the data segment

For G-series TNS or accelerated processes, the size and contents of the extended data segment

The assignment of the data segment size is different from the assignment made when creating a new process with Guardian procedures.

For native processes, the contents of the stack segment from the origin of the stack through the currently in-use location; the balance of the child process stack contains 0

(zero)

For native processes, the size and contents of the globals-heap segment

Job ID

DEFINE mode

Creator access ID (CAID)

3

10 Hewlett-Packard Company 527186-003

System Functions (f - i) fork(2)

Process access ID (PAID)

Security group list

Job ancestor or GMOM

Unread system message index count (PCBMCNT)

This attribute assignment is different from the assignment made when creating a new process with Guardian procedures.

Outstanding incoming and outgoing message limits

This attribute assignment is different from the assignment made when creating a new process with Guardian procedures.

Login, remote login, and saveabend flags

File creation mask

The Guardian attributes of the child process differ from those of the parent process in the following ways:

Segments created or shared using Guardian procedures such as

SEGMENT_ALLOCATE_ are not inherited.

The child process does not inherit the parent process extended swap file (if any). For a

G-series TNS process or an accelerated process, the extended data segment is managed by the Kernel Managed Storage Facility (KMSF).

The child’s process name is system-generated if the RUNNAMED option is set in the program file. Otherwise the process is unnamed.

The DEFINEs inheritance for the child depends on the parent’s DEFINE mode.

The process identification number (PIN) of the child process is unrelated to that of the parent process. The PIN of the child process is unrestricted if both of the following are true:

— The HIGHPIN flag is set in the program file and any user library file.

— The PIN of the parent process was unrestricted.

If the PIN of the child process is restricted, then the PIN is in the range 0 through 254.

The MOM field for the child process is set to 0 (zero).

System debugger selection for the child process is based on Inspect mode and OSS read access rights on the program file.

Code breakpoints and memory breakpoints are not inherited.

For detailed information about Guardian process attributes, see the PROCESS_LAUNCH_ procedure in the Guardian Procedure Calls Reference Manual.

Sharing Guardian Files

After a successful call to the fork( ) function, the initial position within an EDIT file (file code

101) in the Guardian file system (a file in /G) that was opened by a call to the OSS open( ) function is the same for both the parent and child processes. However, the position is not shared; that is, changing the position used by one process does not change the position used by the other process.

527186-003 Hewlett-Packard Company 3

11

fork(2) OSS System Calls Reference Manual

Floating-Point Data

If the parent process uses IEEE floating-point data, the child process inherits all of the floatingpoint register contents of the parent process and any computation started before the fork( ) function call completes in the child process. The contents of the status and control register are also inherited.

RETURN VALUES

Upon successful completion, the fork( ) function returns the value 0 (zero) to the child process and returns the PID of the child process to the parent process. If the fork( ) function fails, the value -1 is returned to the parent process, no child process is created, and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the fork( ) function sets errno to the corresponding value:

[EACCES]

[EAGAIN]

[EIO]

Open for execute access on the code file or any library file was denied.

System resources such as disk space, process control block (PCB) space, MAP-

POOL space, stack space, or PFS space are temporarily inadequate.

Some physical input or output error has occurred. Either a file cannot be opened because of an input or output error or data has been lost during an input or output transfer. This value is used only for errors on the object file of a loaded program or library, or during data transfer with a Guardian environment home terminal.

[ENOMEM] Required resources are not available. Subsequent calls to the same function will not succeed for the same reason.

Possible causes of this error include insufficient primary memory (stack, globals, or heap) for the new process.

[ENOTOSS] The calling process is not an OSS process. The fork( ) function cannot be called from the Guardian environment.

[EUNKNOWN]

Unknown error. An unrecognized or very obscure error occurred. If this error occurs, follow site-defined procedures for reporting software problems to

HP.

RELATED INFORMATION

Functions: exec(2), _exit(2), exit(3), raise(3), semop(2), shmat(2), sigaction(2),

tdm_execve(2), tdm_execvep(2), tdm_fork(2), tdm_spawn(2), tdm_spawnp(2), times(3),

ulimit(3), umask(2), wait(2).

STANDARDS CONFORMANCE

The POSIX standards leave some features to the implementing vendor to define. The following features are affected in the HP implementation:

The child process shares directory streams with the parent. They share the same block of directory entries, but each stream can be used by only one of the processes.

Guardian attributes are associated with the new OSS process. See Guardian Attributes under DESCRIPTION.

3

12 Hewlett-Packard Company 527186-003

System Functions (f - i) fork(2)

The following are HP extensions to the XPG4 Version 2 specification:

The [EFAULT], [ENOTOSS], and [EUNKNOWN] error values are HP extensions.

527186-003 Hewlett-Packard Company 3

13

fstat(2)

NAME

fstat - Provides information about an open file

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/types.h>

/* optional except for POSIX.1 */

#include <sys/stat.h> int fstat(

int filedes,

struct stat *buffer);

PARAMETERS

filedes buffer

Specifies an open file descriptor obtained from a successful call to the accept( ),

creat( ), dup( ), dup2( ), fcntl( ), open( ), pipe( ), socket( ), or socketpair( ) function.

Points to a stat structure, into which information is placed about the file. The stat structure is described in the sys/stat.h header file.

DESCRIPTION

The fstat( ) function obtains information about the open file associated with the filedes parameter.

The file information is written to the area specified by the buffer parameter, which is a pointer to a stat structure with ths definition from the sys/stat.h header file:

struct stat { dev_t st_dev; ino_t st_ino; mode_t st_mode; nlink_t st_nlink; char filler_1[2]; uid_t st_uid; gid_t st_gid; char filler_2[4]; dev_t st_rdev; off_t st_size; time_t st_atime; time_t st_mtime; time_t st_ctime; int64_t reserved[3];

};

The fstat( ) function updates any time-related fields associated with the file before writing into the stat structure, unless it is a read-only fileset. Time-related fields are not updated for read-only

OSS filesets.

The fields in the stat structure have these meanings and content:

st_dev

OSS device identifier for a fileset.

Values for local OSS objects are listed next. Values for local Guardian objects are described in Use on Guardian Objects, and values for remote Guardian or

OSS objects are described in Use on Remote Objects, later in this reference page.

3

14 Hewlett-Packard Company

OSS System Calls Reference Manual

527186-003

System Functions (f - i) fstat(2) st_ino st_mode

527186-003

For Contains

Regular file

Directory

ID of device containing directory entry

ID of device containing directory

Pipe or FIFO ID of special fileset for pipes

AF_INET or AF_INET6 socket ID of special fileset for sockets

AF_UNIX socket ID of device containing the fileset in which the socket file was created

/dev/null

/dev/tty

ID of device containing directory entry

ID of device containing directory entry

File serial number (inode number). The file serial number and OSS device identifier uniquely identify a regular OSS file within an OSS fileset.

Values for OSS objects are listed next. Values for Guardian objects are described in Use on Guardian Objects, later in this reference page.

For Contains

Regular file

Directory

File serial number (unique)

File serial number (unique)

Pipe or FIFO

AF_UNIX socket

File serial number (unique)

AF_INET or AF_INET6 socket File serial number (not unique within the

HP NonStop node)

File serial number of the socket file

(unique)

/dev/null

/dev/tty

File serial number (unique)

File serial number (unique)

The st_ino value for all node entries in /E (including the entry for the logical link from the local node name to the root fileset on the local node) is the value for the root fileset on the corresponding node. If normal conventions are followed, this value is always 0 (zero), so entries in /E appear to be nonunique.

Values for objects on remote nodes are unique only among the values for objects within the same fileset on that node.

File mode. These bits are ORed into the st_mode field:

S_IFMT

File type. This field can contain one of these values:

S_IFCHR

S_IFDIR

S_IFIFO

Character special file.

Directory.

Pipe or FIFO.

S_IFREG

Regular file.

S_IFSOCK

Socket.

For an AF_INET or AF_INET6 socket, the user default permissions are returned for the permission bits. The access flags are set to read and write.

For an AF_UNIX socket, the user permissions

Hewlett-Packard Company 3

15

fstat(2) OSS System Calls Reference Manual st_nlink

from the inode for the socket are returned for the permission bits. The access flags are also returned from the inode.

S_IRWXG

Group class

S_IRWXO

Other class

S_IRWXU

S_ISGID

Owner class

Set group ID on execution

S_ISUID

S_ISVTX

Set user ID on execution

Sticky bit; used only for directories (not ORed for files in /G, the

Guardian file system)

S_NONSTOP Regular file in the OSS file system protected by disk process checkpointing. (Files in /G cannot have this bit set.)

When set, indicates that return from a write operation does not occur until both the primary and backup disk processes have the data (thereby protecting the data against a single point of failure).

OSS file-system data caching is disabled for write operations on files for which this bit is set. Performance is slower than when caching is used, but data integrity protection increases. Performance is faster than when the O_SYNC bit in the open( ) function oflag parameter is used, but data integrity protection is less than that provided by O_SYNC use.

S_TRUST

Indicates that the file does not contain code for an uncooperative | process or code to examine or modify I/O buffers. This flag | suppresses operating system protection of the buffers when the | memory segment containing the buffers is not shared. This flag | applies only to loadfiles for a process and can be set only by a user with appropriate privileges (the super ID).

|

S_TRUSTSHARED

Indicates that the file does not contain code for an uncooperative | process or code to examine or modify I/O buffers. This flag suppresses operating system protection of the buffers regardless |

| of whether the memory segment containing the buffers is shared.

|

This flag applies only to loadfiles for a process and can be set | only by a user with appropriate privileges (the super ID).

Values for Guardian objects are described in Use on Guardian Objects, later in this reference page.

Number of links.

Values for OSS objects are listed next. Values for Guardian objects are described in Use on Guardian Objects, later in this reference page.

3

16 Hewlett-Packard Company 527186-003

System Functions (f - i) fstat(2) st_uid st_gid st_rdev

For Contains

Regular file

Directory

FIFO

Pipe

Number of links to the file

Number of links to the directory

Number of links to the file

-1

AF_INET or AF_INET6 socket 0 (zero)

AF_UNIX socket Number of links to the socket file

/dev/null

/dev/tty

Number of links to the file

Number of links to the file

User ID.

Values for OSS objects are listed next. Values for Guardian objects are described in Use on Guardian Objects, later in this reference page.

For Contains

Regular file

Directory

User ID of the file owner

User ID of the file owner

Pipe or FIFO User ID of the file owner

AF_INET or AF_INET6 socket User ID of the calling process

AF_UNIX socket

/dev/null

/dev/tty

User ID of the creator of the socket file

User ID of the super ID

User ID of the super ID

Group ID.

Values for OSS objects are listed next. Values for Guardian objects are described in Use on Guardian Objects, later in this reference page.

For Contains

Regular file

Directory

Group ID of the file group

Group ID of the file group

Pipe or FIFO Group ID of the file group

AF_INET or AF_INET6 socket Group ID of the calling process

AF_UNIX socket

/dev/null

/dev/tty

Group ID of the creator of the socket file

Group ID of the super ID

Group ID of the super ID

Remote device ID.

Values for OSS objects are listed next. Values for Guardian objects are described in Use on Guardian Objects, later in this reference page.

527186-003 Hewlett-Packard Company 3

17

fstat(2) OSS System Calls Reference Manual st_size st_atime st_mtime

For Contains

Regular file

Directory

Undefined

Undefined

Pipe or FIFO Undefined

AF_INET or AF_INET6 socket 0 (zero)

AF_UNIX socket

/dev/null

/dev/tty

0 (zero)

Undefined

ID of the device

File size.

Values for OSS objects are listed next. Values for Guardian objects are described in Use on Guardian Objects, later in this reference page.

For Contains

Regular file

Directory

Size of the file in bytes

4096

Pipe or FIFO 0 (zero)

AF_INET or AF_INET6 socket 0 (zero)

AF_UNIX socket

/dev/null

/dev/tty

0 (zero)

0 (zero)

0 (zero)

Access time.

Values for OSS objects are listed next. Values for Guardian objects are described in Use on Guardian Objects, later in this reference page.

For Contains

Regular file

Directory

Time of the last access

Time of the last access

Pipe or FIFO Time of the last access

AF_INET or AF_INET6 socket Value maintained in the socket data structure

AF_UNIX socket

/dev/null

/dev/tty

Value retrieved from the inode

Current time

Composite value of the times of all openers of the file

For the /E entry of the local node, the value is the time of the most recent mounting of the root fileset.

Modification time.

Values for OSS objects are listed next. Values for Guardian objects are described in Use on Guardian Objects, later in this reference page.

3

18 Hewlett-Packard Company 527186-003

System Functions (f - i) fstat(2) st_ctime

For Contains

Regular file

Directory

Time of the last data modification

Time of the last modification

Pipe or FIFO Time of the last data modification

AF_INET or AF_INET6 socket Value maintained in the socket data structure

AF_UNIX socket

/dev/null

/dev/tty

Value retrieved from the inode

Current time

Composite value of the times of all openers of the file

For the /E entry of the local node, the value is the time of the most recent mounting of the root fileset.

Status change time.

Values for OSS objects are listed next. Values for Guardian objects are described in Use on Guardian Objects, later in this reference page.

For Contains

Regular file

Directory

Time of the last file status change

Time of the last file status change

Pipe or FIFO Time of the last file status change

AF_INET or AF_INET6 socket Value maintained in the socket data structure

AF_UNIX socket

/dev/null

/dev/tty

Value retrieved from the inode

Current time

Composite value of the times of all openers of the file

For the /E entry of the local node, the value is the time of the most recent mounting of the root fileset.

Use on Guardian Objects

The st_dev and st_ino fields of the stat structure do not uniquely identify Guardian files (files in

/G).

The st_dev field is unique for /G, for each disk volume, and for each Telserv process (or other process of subdevice type 30), because each of these is a separate fileset.

The S_ISGUARDIANOBJECT macro can indicate whether an object is a Guardian object when the st_dev field is passed to the macro. The value of the macro is TRUE if the object is a

Guardian object and FALSE otherwise.

The st_ino field is a nonunique encoding of the Guardian filename.

The st_rdev field contains a unique minor device number for each entry in /G/ztnt/, representing each Telserv process subdevice.

The st_size field of an EDIT file (file code 101) is the actual (physical) end of file, not the number of bytes in the file. For directories, st_size is set to 4096.

When an OSS function is called for a Guardian EDIT file, the st_mtime field is set to the last modification time. The st_atime field indicates the last time the file was opened, and the

st_ctime field is set equal to st_mtime. No other time-related fields are updated by OSS function

527186-003 Hewlett-Packard Company 3

19

fstat(2) OSS System Calls Reference Manual

calls.

The st_ctime and st_atime fields for Guardian regular disk files (except for EDIT files) are updated by OSS function calls, not by Guardian procedure calls.

The time fields for /G, /G/vol, and /G/vol/subvol always contain the current time.

The mapping between Guardian files and their corresponding file types described in the st_mode field is listed next:

Table 3

2. Guardian File Type Mappings

Example in /G

Guardian

File Type st_mode

File Type Permissions

/G

vol

N/A

Disk volume

vol/subvol Subvolume

vol/subvol/fileid Disk file

vol/#123

ztnt ztnt/#pty0001 vol1/zyq00001

Directory

Directory

Directory

Regular file r-xr-xr-x rwxrwxrwx rwxrwxrwx

See following text

Temporary disk file Regular file

Subtype 30 process Directory

See following text

--x--x--x

Character special rw-rw-rwSubtype 30 process with qualifier

Subvolume Directory ---------

A Guardian file classified as a directory is always owned by the super ID.

Guardian permissions are mapped as listed:

A Guardian network or any user permission is mapped to an OSS other permission.

A Guardian community or group user permission is mapped to an OSS group permission.

A Guardian user or owner permission is mapped to an OSS owner permission.

A Guardian super ID permission is an OSS super ID permission.

Guardian read permission is mapped to OSS read permission.

Guardian write permission is mapped to OSS write permission.

Guardian execute permission is mapped to OSS execute permission.

Guardian purge permission is ignored.

Users are not allowed read access to Guardian processes.

OSS file permissions are divided into three groups (owner, group, and other) of three permission bits each (read, write, and execute). Note that the OSS permission bits do not distinguish between remote and local users as Guardian security does; local and remote users are treated alike.

Use on Remote Objects

The content of the st_dev field of the stat structure is unique for each node in /E because each node is a separate fileset. Values for directories within /E are the same as values for objects on the local HP NonStop node.

The S_ISEXPANDOBJECT macro can indicate whether an object in the /E directory is on a remote HP NonStop server node when the st_dev field is passed to the macro. The value of the macro is TRUE if the object is on a remote HP NonStop node and FALSE otherwise.

3

20 Hewlett-Packard Company 527186-003

System Functions (f - i) fstat(2)

RETURN VALUES

Upon successful completion, the value 0 (zero) is returned. Otherwise, the value -1 is returned, and errno is set to indicate the error.

ERRORS

If any of these conditions occurs, the fstat( ) function sets errno to the corresponding value:

[EBADF]

[EFAULT]

[EFSBAD]

[EIO]

The filedes parameter is not a valid file descriptor.

The buffer parameter points to a location outside of the allocated address space of the process.

The program attempted an operation involving a fileset with a corrupted fileset catalog.

An input or output error occurred. The device holding the file might be in the down state, or both processors that provide access to the device might have failed.

[EISGUARDIAN]

The value used for the filedes parameter is appropriate only in the Guardian environment.

[ENETDOWN]

The filedes parameter specifies a file on a remote HP NonStop node, but communication with the remote node has been lost.

[ENOROOT] The program attempted an operation while the root fileset was unavailable.

[ENXIO] An invalid device or address was specified during an input or output operation on a special file. One of these events occurred:

A device was specified that does not exist, or a request was made beyond the limits of the device.

The fileset containing the requestor’s current working directory or root directory is not mounted. This error can occur after failure and restart of an OSS name server process until the fileset has been repaired and remounted.

[EWRONGID] One of these conditions occurred:

The process attempted an operation on an input/output process (such as a terminal server process) that has failed or is in the down state.

The processor for the disk process of the specified file failed during an input or output operation, and takeover by the backup process occurred.

The open file descriptor has migrated to a new processor, but the new processor lacks a resource or system process needed for using the file descriptor.

The file descriptor specified by the filedes parameter can only be closed.

For all other error conditions, errno is set to the appropriate Guardian file-system error number.

See the Guardian Procedure Errors and Messages Manual for more information about a specific

Guardian file-system error.

527186-003 Hewlett-Packard Company 3

21

fstat(2) OSS System Calls Reference Manual

RELATED INFORMATION

Functions: chmod(2), chown(2), link(2), mknod(2), open(2), pipe(2), utime(2).

STANDARDS CONFORMANCE

The HP implementation does not return the errno value [EOVERFLOW].

The POSIX standards leave some features to the implementing vendor to define. These features are affected in the HP implementation:

For files other than regular disk files, the st_size field of the stat structure is set to 0

(zero). For directories, st_size is set to 4096.

The S_IRWXU, S_IRWXG, S_IRWXO, S_IFMT, S_ISVTX, S_NONSTOP,

S_ISGID, and S_ISUID bits are ORed into the st_mode field of the stat structure.

HP extensions to the XPG4 Version 2 specification are:

The errno values [EFAULT], [EFSBAD], [EIO], [EISGUARDIAN], [ENETDOWN],

[ENOROOT], [ENXIO], and [EWRONGID] can be returned by the fstat( ) function.

3

22 Hewlett-Packard Company 527186-003

System Functions (f - i) fstatvfs(2)

NAME

fstatvfs - Gets fileset information for an open file

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/statvfs.h> int fstatvfs(

int filedes,

struct statvfs *buffer);

PARAMETERS

filedes buffer

Specifies an open file descriptor obtained from a successful call to the creat( ),

dup( ), dup2( ), fcntl( ), or open( ) function.

Points to a statvfs structure that is to hold the returned information for the

fstatvfs( ) call.

DESCRIPTION

The fstatvfs( ) function returns descriptive information about a mounted fileset. The information is returned in a statvfs structure, which has this definition from the sys/statvfs.h header file:

typedef struct statvfs { unsigned long unsigned long unsigned long unsigned long unsigned long unsigned long unsigned long unsigned long unsigned long char unsigned long unsigned long char unsigned long unsigned long unsigned long

} statvfs_t; f_bsize; f_frsize; f_blocks; f_bfree; f_bavail; f_files; f_ffree; f_favail; f_fsid; f_basetype[FSTYPSZ]; f_flag; f_namemax; f_fstr[32]; f_bminavail; f_bmaxavail; f_filler[5];

The fields in this structure have these meanings and content:

f_bsize

Fileset block size:

527186-003 Hewlett-Packard Company 3

23

fstatvfs(2) OSS System Calls Reference Manual f_frsize f_blocks f_bfree

For Contains

Regular file

Directory

FIFO

/dev/null

4096

4096

4096

4096

Object in /G

/G

4096

4096

Terminal device file 4096

/E

4096

Fundamental file system block size:

For Contains

Regular file

Directory

FIFO

/dev/null

4096

4096

4096

4096

Object in /G

/G

4096

4096

Terminal device file 4096

/E

4096

Total number of blocks in fileset, in units of f_frsize:

For Contains

Regular file

Directory

FIFO

/dev/null

Number of blocks on all volumes ever used in the fileset.

Number of blocks on all volumes ever used in the fileset.

Number of blocks on all volumes ever used in the fileset.

Number of blocks on all volumes ever used in the fileset.

Object in /G

/G

Terminal device file 0

/E

0

Number of blocks on the volume containing the object.

0

Total number of free blocks in fileset:

3

24 Hewlett-Packard Company 527186-003

System Functions (f - i) fstatvfs(2) f_bavail f_files

For Contains

Regular file

Directory

FIFO

/dev/null

Number of free blocks on all volumes currently in the storage-pool file for the fileset.

Number of free blocks on all volumes currently in the storage-pool file for the fileset.

Number of free blocks on all volumes currently in the storage-pool file for the fileset.

Number of free blocks on all volumes currently in the storage-pool file for the fileset.

Object in /G

/G

Terminal device file 0

/E

0

Number of free blocks in the volume containing the object.

0

Number of free blocks available to a process without appropriate privileges:

For Contains

Regular file

Directory

FIFO

/dev/null

Object in /G

/G

0

Terminal device file 0

/E

0

Number of free blocks on all volumes currently in the storage-pool file for the fileset.

Number of free blocks on all volumes currently in the storage-pool file for the fileset.

Number of free blocks on all volumes currently in the storage-pool file for the fileset.

Number of free blocks on all volumes currently in the storage-pool file for the fileset.

Number of free blocks in the volume containing the object.

Total number of file serial numbers (inode numbers) in the fileset:

527186-003 Hewlett-Packard Company 3

25

fstatvfs(2) OSS System Calls Reference Manual f_ffree f_favail

For Contains

Regular file

Directory

FIFO

/dev/null

Number of inode numbers in the fileset.

Number of inode numbers in the fileset.

Number of inode numbers in the fileset.

Number of inode numbers in the fileset.

Object in /G

/G

Terminal device file 0

/E

0

The value of ULONG_MAX.

0

Total number of free file serial numbers (inode numbers) in the fileset:

For Contains

Regular file

Directory

Number of free inode numbers in the fileset.

Number of free inode numbers in the fileset.

FIFO

/dev/null

Object in /G

/G

Terminal device file 0

/E

0

Number of free inode numbers in the fileset.

Number of free inode numbers in the fileset.

The value of ULONG_MAX.

0

Number of file serial numbers (inode numbers) available to a process without appropriate privileges:

For Contains

Regular file

Directory

FIFO

/dev/null

Number of free inode numbers in the fileset.

Number of free inode numbers in the fileset.

Number of free inode numbers in the fileset.

Number of free inode numbers in the fileset.

Object in /G

/G

Terminal device file 0

/E

0

The value of ULONG_MAX.

0

3

26 Hewlett-Packard Company 527186-003

System Functions (f - i) f_fsid f_basetype f_flag

Fileset identifier:

For Contains

Regular file

Directory

FIFO

/dev/null

Lower 32 bits of the st_dev field in the stat structure.

Lower 32 bits of the st_dev field in the stat structure.

Lower 32 bits of the st_dev field in the stat structure.

Lower 32 bits of the st_dev field in the stat structure.

Object in /G

/G

Lower 32 bits of the st_dev field in the stat structure.

Lower 32 bits of the st_dev field in the stat structure.

Terminal device file Lower 32 bits of the st_dev field in the stat structure.

/E

Lower 32 bits of the st_dev field in the stat structure.

Type of file system:

For Contains

Regular file

Directory

FIFO

/dev/null

OSS

OSS

OSS

OSS

Object in /G

/G

GUARDIAN

GUARDIAN

Terminal device file

GUARDIAN

/E EXPAND

Bit mask indicating type of fileset access allowed:

For

Regular file

Directory

FIFO

/dev/null

Object in /G

/G

Contains

2

3

4 if fileset is read/write, 5 if fileset is readonly.

4 if fileset is read/write, 5 if fileset is readonly.

4 if fileset is read/write, 5 if fileset is readonly.

4 if fileset is read/write, 5 if fileset is readonly.

fstatvfs(2)

527186-003 Hewlett-Packard Company 3

27

fstatvfs(2) OSS System Calls Reference Manual

Terminal device file 2

/E

3

The content of the f_flag field can be tested with these symbolic values:

ST_NOSUID

This bit flag is set if the fileset does not allow the setuid bit to be set for its member files.

ST_NOTRUNC

This bit flag is set if the fileset does not truncate filenames.

ST_RDONLY This bit flag is set if the fileset is mounted for read-only access.

f_namemax

Maximum number of character bytes in a filename within the fileset:

f_fstr

For Contains

Regular file

Directory

FIFO

/dev/null

Object in /G

/G

Terminal device file 7

/E

7

8

7

248

248

248

248

Fileset pathname prefix string:

For Contains

Regular file

Directory

FIFO

/dev/null

Object in /G

/E/nodename/G/volume/ZXnnnnnn n, identifying the catalog file and version for the specified file.

/E/nodename/G/volume/ZXnnnnnn n, identifying the catalog file and version for the specified file.

/E/nodename/G/volume/ZXnnnnnn n, identifying the catalog file and version for the specified file.

/E/nodename/G/volume/ZXnnnnnn n, identifying the catalog file and version for the specified file.

/E/nodename/G/volume, identifying the disk volume containing the specified file.

/G

/E/nodename/G

Terminal device file /E/nodename/G

/E /E

3

28 Hewlett-Packard Company 527186-003

System Functions (f - i) fstatvfs(2) f_bminavail

Number of blocks free on the disk volume with the least space remaining:

For Contains

Regular file

Directory

FIFO

/dev/null

Number of blocks.

Number of blocks.

Number of blocks.

Number of blocks.

Object in /G

/G

Terminal device file 0

/E

0

Number of blocks.

0

f_bmaxavail

Number of blocks free on the disk volume with the most space remaining:

For Contains

Regular file

Directory

FIFO

/dev/null

Number of blocks.

Number of blocks.

Number of blocks.

Number of blocks.

Object in /G

/G

Terminal device file 0

/E

0

Number of blocks.

0

NOTES

This function provides compatibility with the System V Interface Definition, Revision 3.

RETURN VALUES

Upon successful completion, the fstatvfs( ) function returns the value 0 (zero). Otherwise, it returns the value -1, and errno is set to indicate the error.

ERRORS

If any of these conditions occurs, the fstatvfs( ) function sets errno to the corresponding value:

[EBADF]

[EFAULT]

[EINTR]

[EINVAL]

[EIO]

The filedes parameter is not a valid file descriptor.

The buffer parameter points to an invalid address.

The function was interrupted by a signal before any data arrived.

The file pointed to by the filedes parameter is an OSS pipe or a socket.

One of these conditions occurred:

The process is a member of a background process group attempting to write to its controlling terminal, the TOSTOP flag is set, the process is neither ignoring nor blocking the SIGTTOU signal, and the process group of the process is orphaned.

A physical I/O error occurred. The device holding the file might be in the down state, or both processors that provide access to the device might have failed. Data might have been lost during a transfer.

527186-003 Hewlett-Packard Company 3

29

fstatvfs(2) OSS System Calls Reference Manual

[EISGUARDIAN]

The value used for the filedes parameter is appropriate only in the Guardian environment.

[ENETDOWN]

The filedes parameter specifies a file on a remote HP NonStop node, but communication with the remote node has been lost.

[EWRONGID] One of these conditions occurred:

The process attempted an input or output operation through an operating system input/output process (such as a terminal server process) that has failed or is in the down state.

The processor for the disk process of the specified file failed during an input or output operation, and takeover by the backup process occurred.

The open file descriptor has migrated to a new processor, but the new processor lacks a resource or system process needed for use of the file descriptor.

The file descriptor specified by the filedes parameter can only be closed.

For all other error conditions, errno is set to the appropriate Guardian file-system error number.

See the Guardian Procedure Errors and Messages Manual for more information about a specific

Guardian file-system error.

RELATED INFORMATION

Functions: fstat(2), lstat(2), stat(2), statvfs(2).

STANDARDS CONFORMANCE

HP extensions to the XPG4 Version 2 specification are:

The errno values [EINVAL], [EISGUARDIAN], [ENETDOWN], and [EWRONGID] can be returned.

3

30 Hewlett-Packard Company 527186-003

System Functions (f - i) fsync(2)

NAME

fsync - Writes modified data and file attributes to permanent storage

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <unistd.h> int fsync(

int filedes);

PARAMETERS

filedes

Specifies an open file descriptor obtained from a successful call to the accept( ),

creat( ), dup( ), dup2( ), fcntl( ), open( ), pipe( ), socket( ), or socketpair( ) function.

DESCRIPTION

The fsync( ) function saves all modifications for the file open specified by the filedes parameter.

On return from the fsync( ) function, all updated data and file attributes have been saved on permanent storage.

Use on Guardian Objects

The filedes parameter can specify any regular file in /G including Guardian EDIT files. Time values are not saved for other file types in /G, such as terminal files.

NOTES

The fsync( ) function offers an alternative to the O_SYNC file status flag and the S_NONSTOP file attribute. Using fsync( ) calls gives an application control over the performance tradeoffs involved in guaranteeing data integrity. OSS file-system caching can be used for files that are protected only by fsync( ) function calls.

RETURN VALUES

Upon successful completion, the fsync( ) function returns the value 0 (zero). Otherwise, it returns the value -1, and errno is set to indicate the error.

ERRORS

If any of these conditions occurs, the fsync( ) function sets errno to the value that corresponds to the condition:

[EBADF]

[EINTR]

[EINVAL]

The filedes parameter is not a valid file descriptor.

The fsync( ) function was interrupted by a signal that was caught.

The filedes parameter, although valid, does not refer to a file on which this operation is possible.

An I/O error occurred during a write to the fileset.

[EIO]

[EISGUARDIAN]

The value used for the filedes parameter is appropriate only in the Guardian environment.

[ENETDOWN]

The filedes parameter specifies a file on a remote HP NonStop node, but communication with the remote node has been lost.

527186-003 Hewlett-Packard Company 3

31

fsync(2) OSS System Calls Reference Manual

[ENXIO] No such device or address. An invalid device or address was specified during an input or output operation on a special file. One of these events occurred:

A device was specified that does not exist, or a request was made beyond the limits of the device.

The fileset containing the requestor’s current working directory or root directory is not mounted. This error can occur after failure and restart of an OSS name server process until the fileset has been repaired and remounted.

[EWRONGID] One of these conditions occurred:

The process attempted an operation through an operating system input/output process (such as a terminal server process) that has failed or is in the down state.

The processor for the disk process of the specified file failed during an input or output operation, and takeover by the backup process occurred.

The open file descriptor has migrated to a new processor, but the new processor lacks a resource or system process needed for using the file descriptor.

The file descriptor specified by the filedes parameter can only be closed.

For all other error conditions, errno is set to the appropriate Guardian file-system error number.

See the Guardian Procedure Errors and Messages Manual for more information about a specific

Guardian file-system error.

RELATED INFORMATION

Functions: open(2), socket(2), stat(2), write(2).

STANDARDS CONFORMANCE

HP extensions to the XPG4 Version 2 specification are:

The errno values [EISGUARDIAN], [ENETDOWN], [ENXIO], and [EWRONGID] can be returned.

3

32 Hewlett-Packard Company 527186-003

System Functions (f - i) ftruncate(2)

NAME

ftruncate - Changes file length

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/types.h> int ftruncate(

int filedes,

off_t length);

PARAMETERS

filedes length

Specifies the descriptor of a file that must be open for writing.

Specifies the new length of the file in bytes.

DESCRIPTION

The ftruncate( ) function changes the length of a file to the size, in bytes, specified by the length parameter.

If the new length is less than the previous length, the ftruncate( ) function removes all data beyond length bytes from the specified file. All file data between the new EOF (end-of-file) and the previous EOF is discarded.

If the new length is greater than the previous length, zeros are added between the previous EOF and the new EOF. If the new length would exceed the file size limit for the calling process, the call to ftruncate( ) fails, and errno is set to [EINVAL].

Full blocks are returned to the fileset so that they can be used again, and the file size is changed to the value of the length parameter.

The ftruncate( ) function has no effect on FIFO special files. This function does not modify the seek pointer of the file. If ftruncate( ) is called for a FIFO, the call fails, and errno is set to

[EINVAL].

Upon successful completion, the ftruncate( ) function marks the st_ctime and st_mtime fields of the file for update. If the file is a regular file, the ftruncate( ) function clears the S_ISUID and

S_ISGID attributes of the file.

RETURN VALUES

Upon successful completion, the value 0 (zero) is returned. Otherwise, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of these conditions occurs, the ftruncate( ) function sets errno to the corresponding value:

[EBADF]

[EFBIG]

[EINTR]

[EINVAL]

The filedes parameter does not specify a valid file descriptor open for writing.

The new file size would exceed the process’s file size limit or the maximum file size.

The function was interrupted by a signal before any data arrived.

One of these conditions occurred:

The file pointed to by the filedes parameter is not a regular file.

The value specified for the length parameter was less than 0 (zero).

527186-003 Hewlett-Packard Company 3

33

ftruncate(2) OSS System Calls Reference Manual

The value specified for the length parameter would cause the file to exceed the file size limit for the calling process.

[EIO] One of these conditions occurred:

The process is a member of a background process group attempting to read from its controlling terminal, the process is ignoring or blocking the

SIGTTIN signal, or the process group is orphaned.

A physical I/O error occurred. The device holding the file might be in the down state, or both processors that provide access to the device might have failed. Data might have been lost during a transfer.

[EISGUARDIAN]

The value used for the filedes parameter is appropriate only in the Guardian environment.

[ENETDOWN]

The filedes parameter specifies a file on a remote HP NonStop node, but communication with the remote node has been lost.

[EROFS] The file resides on a read-only fileset.

For all other error conditions, errno is set to the appropriate Guardian file-system error number.

See the Guardian Procedure Errors and Messages Manual for more information about a specific

Guardian file-system error.

RELATED INFORMATION

Functions: chmod(2), fcntl(2), open(2).

STANDARDS CONFORMANCE

HP extensions to the XPG4 Version 2 specification are:

The errno values [EISGUARDIAN], [ENETDOWN], and [EROFS] can be returned.

3

34 Hewlett-Packard Company 527186-003

System Functions (f - i) getegid(2)

NAME

getegid - Gets the effective group ID

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsecsrl

H-series OSS processes: /G/system/zdllnnn/zsecdll

SYNOPSIS

#include <sys/types.h>

/* optional except for POSIX.1 */

#include <unistd.h> gid_t getegid(void);

DESCRIPTION

The getegid( ) function returns the effective group ID of the calling process.

The real, effective, and saved group IDs are set at login time and when a process with appropriate privileges calls the setgid( ) function. The effective and saved group IDs can also change as a result of executing a set-group-ID program.

NOTES

A process’s effective group ID can be different from the group membership indicated by the operating system process access ID (PAID) of the process.

RETURN VALUES

The getegid( ) function returns the effective group ID. It is always successful.

The "uninitialized" group ID (hexadecimal 80000000) is returned when authentication information of a process is uninitialized.

RELATED INFORMATION

Functions: getgid(2), getgroups(2), setgid(2).

Commands: id(1).

527186-003 Hewlett-Packard Company 3

35

geteuid(2) OSS System Calls Reference Manual

NAME

geteuid - Gets the effective user ID of the current process

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsecsrl

H-series OSS processes: /G/system/zdllnnn/zsecdll

SYNOPSIS

#include <sys/types.h>

/* optional except for POSIX.1 */

#include <unistd.h> uid_t geteuid(void);

DESCRIPTION

The geteuid( ) function returns the effective user ID of the current process.

RETURN VALUES

The geteuid( ) function returns the requested user ID. It is always successful.

When the authentication information for a process is uninitialized, the "uninitialized" user ID

(hexadecimal 80000000) is returned.

RELATED INFORMATION

Functions: getuid(2), setuid(2).

3

36 Hewlett-Packard Company 527186-003

System Functions (f - i) getgid(2)

NAME

getgid - Gets the real group ID

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsecsrl

H-series OSS processes: /G/system/zdllnnn/zsecdll

SYNOPSIS

#include <sys/types.h>

/* optional except for POSIX.1 */

#include <unistd.h> gid_t getgid(void);

DESCRIPTION

The getgid( ) function returns the real group ID of the calling process.

The real, effective, and saved group IDs are set at login time and when a process with appropriate privileges calls the setgid( ) function.

NOTES

A process’s real group ID can be different from the group number in the operating system creator access ID (CAID) for a process.

RETURN VALUES

The getgid( ) function returns the real group ID. It is always successful.

The "uninitialized" group ID (hexadecimal 80000000) is returned when authentication information of a process is uninitialized.

RELATED INFORMATION

Functions: getegid(2), getgroups(2), setgid(2).

Commands: id(1).

527186-003 Hewlett-Packard Company 3

37

getgroups(2) OSS System Calls Reference Manual

NAME

getgroups - Gets the group list of the current process

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsecsrl

H-series OSS processes: /G/system/zdllnnn/zsecdll

SYNOPSIS

#include <unistd.h>

#include <sys/types.h> int getgroups(

int gidsetsize,

gid_t grouplist [ ]);

PARAMETERS

gidsetsize

[EINVAL]

Specifies the number of entries that can be stored in the array pointed to by the

grouplist parameter.

Points to the array in which the group list of the process is stored.

grouplist

DESCRIPTION

The getgroups( ) function gets the group list of the current process. The list is stored in the array pointed to by the grouplist parameter. The gidsetsize parameter indicates the number of entries that can be stored in this array.

The getgroups( ) function never returns more than NGROUPS_MAX entries.

(NGROUPS_MAX is a constant defined in the limits.h header file.) If the gidsetsize parameter is 0 (zero), the getgroups( ) function returns the number of groups in the group list.

The effective group ID may not occur in the returned group ID list if the effective group ID has been changed by executing a set-group-ID program or by calling the setgid( ) function.

RETURN VALUES

Upon successful completion, the getgroups( ) function returns the number of elements stored in the array pointed to by the grouplist parameter. If getgroups( ) fails, then the value -1 is returned and errno is set to indicate the error.

The value 0 (zero) is returned when the authentication information for a process is uninitialized.

ERRORS

If any of the following conditions occurs, the getgroups( ) function sets errno to the corresponding value:

[EFAULT] The gidsetsize and grouplist parameters specify an array that is partially or completely outside the allocated address space of the process.

The gidsetsize parameter is nonzero and smaller than the number of groups in the group list, or the grouplist parameter is out of range.

RELATED INFORMATION

Commands: id(1).

3

38 Hewlett-Packard Company 527186-003

System Functions (f - i) gethostname(2)

NAME

gethostname - Gets the name of the local host

LIBRARY

G-series native OSS processes: /G/system/sysnn/zinetsrl

H-series OSS processes: /G/system/zdllnnn/zinetdll

SYNOPSIS

#include <netdb.h>

int gethostname(

char *address,

int address_len);

PARAMETERS

address

Returns the address of an array of bytes where the host name is stored. If sufficient space is provided, the returned address parameter is NULL terminated.

address_len

Specifies the length of the array pointed to by the address parameter.

DESCRIPTION

The gethostname( ) function retrieves the standard host name of the local host. The name returned corresponds to the host name returned in the Subsystem Command Facility (SCF) command INFO PROCESS for the TCP subsystem.

RETURN VALUES

Upon successful completion, the gethostname( ) function returns a value of 0 (zero). Otherwise, a value of -1 is returned, and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the gethostname( ) function sets errno to the corresponding value:

[EINVAL] The address parameter or address_len parameter refers to an invalid address in the user’s address space.

RELATED INFORMATION

Functions: gethostid(2).

527186-003 Hewlett-Packard Company 3

39

getlogin(2) OSS System Calls Reference Manual

NAME

getlogin - Gets login name

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsecsrl

H-series OSS processes: /G/system/zdllnnn/zsecdll

SYNOPSIS

#include <unistd.h> char *getlogin(void);

DESCRIPTION

The getlogin( ) function returns the login name associated with the current session.

The login name can be a username or a user alias.

The name is normally associated with a login shell at the time a session is created, and it is inherited by all processes descended from the login shell. (This is true even if some of those processes assume another user ID.)

RETURN VALUES

Upon successful completion, the login name is stored in the location pointed to by the returned value.

If the authentication information for a process is uninitialized, a null string is returned.

RELATED INFORMATION

Functions: geteuid(2), getuid(2).

3

40 Hewlett-Packard Company 527186-003

System Functions (f - i) getpeername(2)

NAME

getpeername - Gets the name of the peer socket

LIBRARY

G-series native OSS processes: /G/system/sysnn/zinetsrl

H-series OSS processes: /G/system/zdllnnn/zinetdll

SYNOPSIS

#include <sys/socket.h> int getpeername(

int socket,

struct sockaddr *address,

size_t *address_len

);

PARAMETERS

socket

Specifies the open file descriptor of the socket.

address

Points to a sockaddr structure, where the address of the peer socket is returned.

If the length of the address is greater than the length of the supplied sockaddr structure, the address is truncated when stored.

If the protocol permits connection by unbound clients, and if the peer socket is not bound to an address, then the value stored is unspecified.

The length and format of the address depend on the address family of the socket.

For AF_INET sockets, a pointer to the address structure sockaddr_in can be cast as a struct sockaddr. For AF_INET6 sockets, a pointer to the address structure sockaddr_in6 can be cast as a struct sockaddr.

address_len

Points to a size_t data item, which, on input, specifies the length of the sockaddr structure pointed to by the address parameter, and, on output, specifies the length of the address returned.

DESCRIPTION

The getpeername( ) function retrieves the peer address of the specified socket, stores this address in the sockaddr structure pointed to by the address parameter, and stores the length of this address in the object pointed to by the address_len parameter.

NOTES

A process can use the getsockname( ) function to retrieve the locally bound name of a socket.

RETURN VALUES

Upon successful completion, the getpeername( ) function returns the value 0 (zero). Otherwise, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the getpeername( ) function sets errno to the corresponding value:

[EBADF] The socket parameter is not a valid file descriptor.

[ECONNRESET]

One of the following conditions occurred:

The transport-provider process for this socket is no longer available.

The TCP/IP subsystem for this socket is no longer available.

527186-003 Hewlett-Packard Company 3

41

getpeername(2) OSS System Calls Reference Manual

The connection was forcibly closed by the peer socket.

The socket can only be closed.

[EFAULT]

[EINVAL]

A user-supplied memory buffer cannot be accessed or written.

The socket has been shut down.

[ENOBUFS] There were not enough system resources available to complete the call. A retry at a later time might succeed.

[ENOMEM] Required memory resources were not available. A retry at a later time might succeed.

[ENOTCONN] The socket is not connected or has not had the peer socket previously specified.

[ENOTSOCK] The socket parameter does not refer to a socket.

[EOPNOTSUPP]

The operation is not supported for the protocol of the socket specified by the

socket parameter.

RELATED INFORMATION

Functions: accept(2), bind(2), getsockname(2), socket(2).

STANDARDS CONFORMANCE

The HP implementation does not return the errno value [ENOSR].

The following are HP extensions to the XPG4 specification:

The errno value [ECONNRESET] can be returned when the transport-provider process is unavailable.

3

42 Hewlett-Packard Company 527186-003

System Functions (f - i) getpgid(2)

NAME

getpgid - Gets the process group ID for a specified OSS process

LIBRARY

G-series native OSS processes: /G/system/sysnn/zossksrl

H-series OSS processes: /G/system/zdllnnn/zosskdll

SYNOPSIS

#include <unistd.h> pid_t getpgid(

pid_t pid);

PARAMETERS

pid

Specifies the process ID of the target process. If the specified value is 0 (zero), the target process is the calling process.

DESCRIPTION

The getpgid( ) function returns the process group ID of the process specified by the process ID

pid.

Use From the Guardian Environment

This function cannot be used in the Guardian environment. When the getpgid( ) function is called from the Guardian environment, the call fails and errno is set to [ENOTOSS].

RETURN VALUES

The getpgid( ) function returns the process group ID of the specified process. If an error occurs, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the getpgid( ) function sets errno to the corresponding value.

[EINVAL] The pid parameter is out of range.

[ENOTOSS] The calling process is not an OSS process. The requested operation is not supported from the Guardian environment.

[EPERM]

[ESRCH]

The specified process is not in the same session as the calling process.

The value of the pid parameter does not match the OSS process ID of the calling process or of a child process of the calling process.

RELATED INFORMATION

Functions: exec(2), fork(2), getpgrp(2), setpgid(2), setsid(2), tcsetpgrp(2), tdm_execve(2),

tdm_execvep(2), tdm_fork(2), tdm_spawn(2), tdm_spawnp(2).

STANDARDS CONFORMANCE

The following is an HP extension to the XPG4 Version 2 specification:

The function can return the errno value [ENOTOSS].

527186-003 Hewlett-Packard Company 3

43

getpgrp(2) OSS System Calls Reference Manual

NAME

getpgrp - Gets the process group ID of the calling process

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/types.h>

/* optional except for POSIX.1 */

#include <unistd.h> pid_t getpgrp(void);

DESCRIPTION

The getpgrp( ) function returns the process group ID of the calling process.

Use From the Guardian Environment

Calls to getpgrp( ) from Guardian processes are not successful.

RETURN VALUES

When called by an OSS process, this function returns the requested process group ID. When called by a Guardian process, Guardian trap number 5 is set.

RELATED INFORMATION

Commands: ps(1).

Functions: exec(2), _exit(2), fork(2), kill(2), setpgid(2), setsid(2), tdm_fork(2).

3

44 Hewlett-Packard Company 527186-003

System Functions (f - i) getpid(2)

NAME

getpid - Gets the OSS process ID

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/types.h>

/* optional except for POSIX.1 */

#include <unistd.h> pid_t getpid(void);

DESCRIPTION

The getpid( ) function returns the OSS process ID of the calling process.

Use From the Guardian Environment

Calls to getpid( ) from Guardian processes are not successful.

RETURN VALUES

When called by an OSS process, this function returns the requested OSS process ID. When called by a Guardian process, Guardian trap number 5 is set.

RELATED INFORMATION

Commands: ps(1).

Functions: exec(2), _exit(2), fork(2), kill(2), setpgid(2), setsid(2), tdm_fork(2).

527186-003 Hewlett-Packard Company 3

45

getppid(2) OSS System Calls Reference Manual

NAME

getppid - Gets the parent OSS process ID

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/types.h>

/* optional except for POSIX.1 */

#include <unistd.h> pid_t getppid(void);

DESCRIPTION

The getppid( ) function returns the parent OSS process ID of the calling process. If the parent process terminates or the calling process was created by a Guardian process, getppid( ) returns a parent OSS process ID of 1.

Use From the Guardian Environment

Calls to getppid( ) from Guardian processes are not successful.

RETURN VALUES

When called by an OSS process, this function returns the requested OSS process ID. When called by a Guardian process, Guardian trap number 5 is set.

RELATED INFORMATION

Commands: ps(1).

Functions: exec(2), _exit(2), fork(2), kill(2), setpgid(2), setsid(2), tdm_fork(2).

3

46 Hewlett-Packard Company 527186-003

System Functions (f - i) getpriority(2)

NAME

getpriority - Gets the OSS process scheduling priority

LIBRARY

G-series native OSS processes: /G/system/sysnn/zossksrl

H-series OSS processes: /G/system/zdllnnn/zosskdll

SYNOPSIS

#include <sys/resource.h> int getpriority(

int which,

id_t who);

PARAMETERS

which

Specifies the symbolic value for the source of the nice value to be returned. The following symbolic values defined in the sys/resource.h header file are valid:

who

PRIO_PGRP The nice value for the process group should be returned.

PRIO_PROCESS

The nice value for the process should be returned.

PRIO_USER The nice value associated with the user ID should be returned.

Specifies a numeric value interpreted relative to the which parameter (a process group ID, an OSS process ID, and a user ID, respectively). A 0 (zero) value for the who parameter indicates the current process group ID, OSS process ID, or user ID.

DESCRIPTION

The getpriority( ) function obtains the current priority of a process group, process, or user ID.

The getpriority( ) function returns the highest priority (lowest numerical value) pertaining to any of the specified processes.

Use From the Guardian Environment

This function cannot be called from the Guardian environment. When the getpriority( ) function is called from the Guardian environment, the call fails and errno is set to [ENOTOSS].

RETURN VALUES

Because getpriority( ) can legitimately return the value of -1, set the external variable errno to 0

(zero) before calling the getpriority( ) function. If a value of -1 is returned from getpriority( ), check errno to see whether an error occurred or the value is a legitimate priority.

Upon successful completion, the getpriority( ) function returns an integer in the range -20 through 20. Otherwise, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the getpriority( ) function sets errno to the corresponding value.

[EINVAL] One of the following conditions occurred:

The value specified by the which parameter is invalid.

The value specified as a process group ID, OSS process ID, or user ID by the who parameter is out of range.

527186-003 Hewlett-Packard Company 3

47

getpriority(2) OSS System Calls Reference Manual

[ENOTOSS] The calling process is not an OSS process. The requested operation is not supported from the Guardian environment.

[ESRCH] No process was located using the which and who parameter values specified.

RELATED INFORMATION

Functions: nice(2).

STANDARDS CONFORMANCE

The following is an HP extension to the XPG4 Version 2 specification:

The function can return the errno value [ENOTOSS].

3

48 Hewlett-Packard Company 527186-003

System Functions (f - i) getsockname(2)

NAME

getsockname - Gets the locally bound name of a socket

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/socket.h> int getsockname(

int socket,

struct sockaddr *address,

size_t *address_len

);

PARAMETERS

socket

Specifies the file descriptor of the socket.

address

Points to a sockaddr structure, where the locally bound address of the specified socket is returned.

If the length of the socket address is greater than the length of the supplied

sockaddr structure, the address is truncated when stored.

If the socket has not been bound to a local address, the value stored is unspecified.

The length and format of the address depend on the address family of the socket.

For AF_INET sockets, a pointer to the address structure sockaddr_in can be cast as a struct sockaddr. For AF_INET6 sockets, a pointer to the address structure sockaddr_in6 can be cast as a struct sockaddr.

address_len

Points to a size_t data item, which, on input, specifies the length of the sockaddr structure pointed to by the address parameter, and, on output, specifies the length of the address returned.

DESCRIPTION

The getsockname( ) function retrieves the locally-bound address of the specified socket, stores this address in the sockaddr structure pointed to by the address parameter, and stores the length of this address in the object pointed to by the address_len parameter.

NOTES

A process can use the getpeername( ) function to retrieve the name of a peer socket in a socket connection.

RETURN VALUES

Upon successful completion, the getsockname( ) function returns the value 0 (zero). Otherwise, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occur, the getsockname( ) function sets errno to the corresponding value:

[EBADF] The socket parameter is not a valid file descriptor.

527186-003 Hewlett-Packard Company 3

49

getsockname(2) OSS System Calls Reference Manual

[ECONNRESET]

One of the following conditions occurred:

The transport-provider process for this socket is no longer available.

The TCP/IP subsystem for this socket is no longer available.

The connection was forcibly closed by the peer socket.

The socket can only be closed.

[EFAULT] A user-supplied memory buffer cannot be accessed or written.

[EINVAL] The socket has been shut down.

[ENOBUFS] There was not enough buffer space available to complete the call. A retry at a later time might succeed.

[ENOMEM] Required memory resources were not available. A retry at a later time might succeed.

[ENOTSOCK] The socket parameter does not refer to a socket.

[EOPNOTSUPP]

The specified operation is not supported by the protocol used by the socket.

RELATED INFORMATION

Functions: accept(2), bind(2), getpeername(2), socket(2).

STANDARDS CONFORMANCE

The HP implementation does not return the errno value [ENOSR].

The following are HP extensions to the XPG4 specification:

The errno value [ECONNRESET] can be returned when the transport-provider process is unavailable.

3

50 Hewlett-Packard Company 527186-003

System Functions (f - i) getsockopt(2)

NAME

getsockopt - Gets socket options

LIBRARY

G-series native OSS processes: /G/system/sysnn/zinetsrl

H-series OSS processes: /G/system/zdllnnn/zinetdll

SYNOPSIS

#include <sys/socket.h>

[#include <netinet/in.h>] Required for IP protocol level

[#include <netinet/tcp.h>] Required for TCP protocol level

int getsockopt(

int socket,

int level,

int option_name,

void *option_value,

size_t *option_len

);

PARAMETERS

socket level

Specifies the file descriptor for the socket.

Specifies the protocol level at which the option resides. The following values can be specified for the level parameter in an OSS application program:

IPPROTO_IPV6

Return IP protocol-level options defined for an Internet Protocol version 6 (IPv6) socket

IPPROTO_IP Return IP protocol-level options defined for an Internet Protocol version 4 (IPv4) socket

IPPROTO_TCP

Return TCP protocol-level options defined for a socket

SOL_SOCKET

Return socket-level protocol options defined for a socket

To retrieve options at other levels, supply the appropriate protocol number for the protocol controlling the option. Supported protocol numbers are listed in

/etc/protocols.

option_name

Specifies a single option to be retrieved.

The getsockopt( ) function retrieves information about the following

IPPROTO_IPV6 (IP protocol-level IPv6) options:

IPV6_MULTICAST_IF

Indicates the interface (subnet) used for outbound multicast

UDP datagrams. The interface value is an unsigned int.

IPV6_MULTICAST_HOPS

Indicates the hop limit for outbound multicast UDP datagrams.

The limit is an int that is either:

Between 0 and 255 to indicate the maximum number of hops allowed.

527186-003 Hewlett-Packard Company 3

51

getsockopt(2) OSS System Calls Reference Manual

-1 to indicate that the default value should be used.

IPV6_MULTICAST_LOOP

Indicates that the host belongs to the multicast group that it is sending to, and a copy of the datagram should be sent by loopback to the originating host.

IPV6_UNICAST_HOPS

Indicates the hop limit for outbound unicast UDP datagrams.

The limit is an int that is either:

Between 0 and 255 to indicate the maximum number of hops allowed.

-1 to indicate that the default value should be used.

IPV6_V6ONLY

Indicates that AF_INET6 sockets are restricted to IPv6-only communication.

The getsockopt( ) function retrieves information about the following

IPPROTO_IP (IP protocol-level IPv4) options:

IP_OPTIONS Indicates that the value of the IP_OPTIONS flag should be returned. The IP_OPTIONS flag indicates that options specified in a setsockopt( ) function call are set for each outgoing packet, in conformance with RFC 791.

IP_MULTICAST_IF

Indicates the interface (subnet) used for outbound multicast

UDP datagrams. The interface value is an unsigned int.

IP_MULTICAST_TTL

Indicates the hop limit for outbound multicast UDP datagrams.

The limit is an int that is either:

Between 0 and 255 to indicate the maximum number of hops allowed.

-1 to indicate that the default value should be used.

IP_MULTICAST_LOOP

Indicates that the host belongs to the multicast group that it is sending to, and a copy of the datagram should be sent by loopback to the originating host.

The getsockopt( ) function retrieves information about the following

SOL_SOCKET (socket protocol-level) options:

SO_ACCEPTCONN

Reports whether socket listening is enabled. This option returns an int value in the buffer pointed to by the option_value parameter.

3

52 Hewlett-Packard Company 527186-003

System Functions (f - i)

527186-003

getsockopt(2)

SO_BROADCAST

Reports whether transmission of broadcast messages is supported. This option returns an int value in the buffer pointed to by the option_value parameter.

SO_DEBUG

Reports whether debugging information is being recorded. This option returns an int value in the buffer pointed to by the

option_value parameter.

SO_DONTROUTE

Reports whether outgoing messages should bypass the standard routing facilities and be directed to the appropriate network interface, according to the destination address. (This option is for debugging purposes only and is not recommended.) This option returns an int value in the buffer pointed to by the

option_value parameter.

SO_ERROR

Reports information about error status and clears it. This option returns an int value in the buffer pointed to by the option_value parameter.

SO_KEEPALIVE

Reports whether connections are kept active with periodic transmission of messages. This option returns an int value in the buffer pointed to by the option_value parameter.

SO_LINGER Reports whether the system attempts to deliver data after the

close( ) function is called if unsent data is queued.

The SO_LINGER option is always enabled for AF_INET or

AF_INET6 sockets and is not implemented for AF_UNIX sockets.

This option returns a linger structure value in the buffer pointed to by the option_value parameter.

SO_OOBINLINE

Reports whether the socket leaves received out-of-band data

(data marked urgent) queued with other data (in line) for protocols that support out-of-band data. This option returns an int value in the buffer pointed to by the option_value parameter.

SO_RCVBUF Reports the receive buffer size in bytes. This option returns an

int value in the buffer pointed to by the option_value parameter.

SO_REUSEADDR

Reports whether the rules used in validating addresses supplied by a bind( ) function call should allow reuse of local addresses.

This option returns an int value in the buffer pointed to by the

option_value parameter.

SO_REUSEPORT

Reports whether the rules used in validating ports supplied by a

bind( ) function call should allow reuse of local ports. This option returns an int value in the buffer pointed to by the

option_value parameter.

This option is valid only for UDP ports.

Hewlett-Packard Company 3

53

getsockopt(2) OSS System Calls Reference Manual

SO_SNDBUF Reports the send buffer size in bytes. This option returns an int value in the buffer pointed to by the option_value parameter.

SO_TYPE

Reports the socket type in a form that can be tested against a symbolic value such as SOCK_DGRAM or SOCK_STREAM.

This option returns an int value in the buffer pointed to by the

option_value parameter.

The getsockopt(\|) function retrieves information about the following

IPPROTO_TCP (TCP protocol-level) options:

TCP_MAXRXMT

Reports the maximum retransmission timeout value in multiples of 500 milliseconds. This option returns an int value in the buffer pointed to by the option_value parameter.

TCP_MINRXMT

Reports the minimum retransmission timeout value in multiples of 500 milliseconds. This option returns an int value in the buffer pointed to by the option_value parameter.

TCP_NODELAY

Reports whether data packets are buffered before transmission.

This option returns an int value in the buffer pointed to by the

option_value parameter.

TCP_RXMTCNT

Reports the maximum retransmission count. This option returns an int value in the buffer pointed to by the option_value parameter.

TCP_SACKENA

Reports whether TCP selective acknowledgments are enabled.

This option returns an int value in the buffer pointed to by the

option_value parameter.

TCP_TOTRXMTVAL

Reports the total maximum retransmission duration in multiples of 500 milliseconds. This option returns an int value in the buffer pointed to by the option_value parameter.

Options at other protocol levels vary in format and name.

option_value

Points to the buffer to receive the option value. The data type of the value returned for each option is indicated in the description of option_name.

If the length of the value returned for an option is greater than the length of the supplied option_value buffer, the value is truncated when stored.

option_len

Points to a size_t data item, which, on input, specifies the length of the supplied buffer pointed to by the option_value parameter, and, on output, specifies the length of the value returned in the supplied buffer.

3

54 Hewlett-Packard Company 527186-003

System Functions (f - i) getsockopt(2)

DESCRIPTION

The getsockopt( ) function allows an application program to query socket options. The calling program specifies the file descriptor, the option, and a place to store the requested information.

The operating system gets the socket option information from its internal data structures and passes the requested information back to the calling program.

Upon successful completion, the getsockopt( ) function returns the value of the specified option in the buffer pointed to by the option_value parameter. For options that can be classified as disabled or enabled, a value of 0 (zero) indicates that the option is disabled and a value of 1 indicates that the option is enabled. The socket-level options can be enabled or disabled by the set-

sockopt( ) function.

RETURN VALUES

Upon successful completion, the getsockopt( ) function returns the value 0 (zero). Otherwise, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the getsockopt( ) function sets errno to the corresponding value:

[EBADF] The socket parameter is not a valid file descriptor.

[ECONNRESET]

One of the following conditions occurred:

The transport-provider process for this socket is no longer available.

The TCP/IP subsystem for this socket is no longer available.

The connection was forcibly closed by the peer socket.

The socket can only be closed.

[EFAULT]

[EINVAL]

A user-supplied memory buffer cannot be accessed or written.

One of the following conditions occurred:

The specified option is not valid at the specified socket level.

The socket has been shut down.

[ENOBUFS] There was not enough buffer space available to complete the call. A retry at a later time might succeed.

[ENOMEM] Required memory resources were not available. A retry at a later time might succeed.

[ENOPROTOOPT]

The specified option is not supported by the protocol used by the socket.

[ENOTSOCK] The socket parameter does not refer to a socket.

[EOPNOTSUPP]

The specified operation is not supported by the protocol used by the socket.

RELATED INFORMATION

Functions: bind(2), close(2), endprotoent(3), getprotobynumber(3), getprotoent(3), setpro-

toent(3), setsockopt(2), socket(2), socketpair(2).

527186-003 Hewlett-Packard Company 3

55

getsockopt(2) OSS System Calls Reference Manual

STANDARDS CONFORMANCE

The HP implementation does not:

Implement the SO_LINGER option for AF_UNIX sockets.

Return the errno value [ENOSR].

The following are HP extensions to the XPG4 specification:

The errno value [ECONNRESET] can be returned when the transport provider process is unavailable.

The SO_REUSEPORT option is supported.

3

56 Hewlett-Packard Company 527186-003

System Functions (f - i) gettimeofday(2)

NAME

gettimeofday - Gets date and time

LIBRARY

G-series native OSS processes: /G/system/sysnn/zossksrl

H-series OSS processes: /G/system/zdllnnn/zosskdll

SYNOPSIS

#include <sys/time.h> int gettimeofday(

struct timeval *tp,

struct timezone *tzp);

PARAMETERS

tp tzp

Points to a timeval structure, defined in the sys/time.h file. The timeval structure contains the current time when the call is completed. If a null pointer is specified, then the current time is not returned.

Points to a timezone structure, defined in the sys/time.h file. The timezone structure contains the current time zone when the call is completed. If a null pointer is specified, then the current time zone is not returned.

DESCRIPTION

The gettimeofday( ) function gets the system values for the current time and time zone. The time is expressed in seconds and microseconds since midnight (0 hour), January 1, 1970.

The timeval structure contains the following fields:

tv_sec tv_usec

The number of whole seconds of elapsed time.

The number of additional microseconds of elapsed time.

The timezone structure contains the following fields:

tz_minuteswest

The local time zone, measured in minutes of time westward from Coordinated

Universal Time (Greenwich, England).

tz_dsttime

A value that indicates which daylight-saving time correction applies locally during the appropriate part of the year.

This value is always set to 0 (zero) upon successful completion, because the information required to return an accurate nonzero value is not available.

Use From the Guardian Environment

This function cannot be used in the Guardian environment. When the gettimeofday( ) function is called from the Guardian environment, the call fails and errno is set to [ENOTOSS].

NOTES

The gettimeofday( ) function is supported for compatibility with BSD programs. This function provides a process-local time-zone parameter in addition to the systemwide time and date.

RETURN VALUES

Upon successful completion, the value 0 (zero) is returned. Otherwise, the value -1 is returned and errno is set to indicate the error.

527186-003 Hewlett-Packard Company 3

57

gettimeofday(2) OSS System Calls Reference Manual

ERRORS

If any of the following conditions occurs, the gettimeofday( ) function sets errno to the corresponding value:

[EFAULT] A parameter points to an invalid address.

[ENOTOSS] The calling process is not an OSS process. The requested operation is not supported from the Guardian environment.

RELATED INFORMATION

Functions: ctime(3), strftime(3).

Commands: date(1).

STANDARDS CONFORMANCE

In the HP implementation:

The tzp parameter is not a type void data item.

The tz_dsttime field is always set to 0 (zero).

The following are HP extensions to the XPG4 Version 2 specification:

This function returns errno values.

The behavior when the tzp parameter is a null pointer is specified.

3

58 Hewlett-Packard Company 527186-003

System Functions (f - i) getuid(2)

NAME

getuid - Gets the the real user ID of the current process

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsecsrl

H-series OSS processes: /G/system/zdllnnn/zsecdll

SYNOPSIS

#include <sys/types.h>

/* optional except for POSIX.1 */

#include <unistd.h> uid_t getuid(void);

DESCRIPTION

The getuid( ) function returns the real user ID of the current process.

NOTES

A process’s real user ID is not always numerically equal to its operating system creator access ID

(CAID).

RETURN VALUES

The getuid( ) function returns the requested user ID. It is always successful.

When the authentication information for a process is uninitialized, the "uninitialized" user ID

(hexadecimal 80000000) is returned.

RELATED INFORMATION

Functions: geteuid(2), setuid(2).

527186-003 Hewlett-Packard Company 3

59

ioctl(2) OSS System Calls Reference Manual

NAME

ioctl - Controls device files

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <stropts.h>

#include <ioctl.h> int ioctl(

int filedes,

int request,

/ * arg */ . . . );

The ellipsis (. . .) indicates that the function is variable.

PARAMETERS

filedes

Specifies the open file descriptor of the tty device or socket.

request arg

Specifies the function to be performed for the tty device or socket.

A pointer to data to be used by the function or to be provided by the function.

DESCRIPTION

The ioctl( ) function controls the operations of devices. The requests that ioctl( ) performs on devices are device-specific.

The ioctl( ) function passes the request parameter to the file designated by the open file descriptor

filedes. If the filedes parameter identifies an unsupported device type, the function call fails, and

errno is set to the value [EINVAL].

Valid values for the request parameter for AF_INET or AF_INET6 sockets are:

FIONREAD

Gets the number of bytes available for reading and stores it at the int pointed at by arg.

SIOCATMARK

Examines whether the socket is at an out-of-band data mark and stores it at the

int pointed at by arg. A nonzero value indicates that the socket is at an out-ofband data mark; a zero value indicates that the socket is not at an out-of-band data mark.

SIOCGIFNUM

Gets the number of interfaces that have been configured and stores it at the int pointed at by arg.

FIONBIO

Sets the blocking I/O/nonblocking I/O flag for the socket. If the arg is zero, the socket is set to blocking I/O; otherwise, the socket is set to nonblocking I/O and the flag is stored at the int pointed at by arg.

SIOCADDRT Adds a route. The data structure pointed to by arg is of type rtentry.

SIOCDELRT Deletes a route. The data structure pointed to by arg is of type rtentry.

3

60 Hewlett-Packard Company 527186-003

System Functions (f - i) ioctl(2)

SIOCSIFADDR

Sets the interface address. The data structure pointed to by arg is of type ifreq.

Returns the error [EOPNOTSUPP].

SIOCSIFDSTADDR

Sets the destination address on a point-to-point interface. The data structure pointed to by arg is of type ifreq. Returns the error [EOPNOTSUPP].

SIOCSIFFLAGS

Sets the interface flags. The data structure pointed to by arg is of type ifreq.

Returns the error [EOPNOTSUPP].

SIOCSIFBRDADDR

Sets the destination address on a broadcast interface. The data structure pointed to by arg is of type ifreq. Returns the error [EOPNOTSUPP].

SIOCSIFNETMASK

Sets the network address mask, which specifies the portion of the IP host ID and

IP network number that should be masked to define a subnet. The data structure pointed to by arg is of type ifreq. Returns the error [EOPNOTSUPP].

SIOCSARP

Sets the ARP protocol address entry in the translation table. The data structure pointed to by arg is of type arpreq.

SIOCDARP

Deletes the ARP protocol address entry from the translation table. The data structure pointed to by arg is of type arpreq.

SIOCGIFADDR

Gets the interface address. The data structure pointed to by arg is of type ifreq.

Returns the error [ENXIO].

SIOCGIFDSTADDR

Gets the destination address on a point-to-point interface. The data structure pointed to by arg is of type ifreq.

SIOCGIFFLAGS

Gets the interface flags. The data structure pointed to by arg is of type ifreq.

SIOCGIFBRDADDR

Gets the destination address on a broadcast interface. The data structure pointed to by arg is of type ifreq.

SIOCGIFCONF

Gets the interface configuration list. The data structure pointed to by arg is of type ifconf.

SIOCGIFNETMASK

Gets the network address mask, which specifies the portion of the IP host ID and

IP network number that should be masked to define a subnet. The data structure pointed to by arg is of type ifreq.

SIOCGARP

Gets the ARP protocol address entry from the translation table. The data structure pointed to by arg is of type arpreq.

The values valid for the request parameter for tty devices are:

TIOCGWINSZ

Causes the current values for the Telserv window identified by the filedes parameter to be stored in the winsize structure pointed to by arg.

527186-003 Hewlett-Packard Company 3

61

ioctl(2) OSS System Calls Reference Manual

TIOCSWINSZ

Causes the values stored in the winsize structure pointed to by arg to be sent to the Telserv window identified by the filedes parameter.

When the request parameter specifies either TIOCGWINSZ or TIOCSWINSZ, the third and only additional parameter is a pointer to:

struct winsize { unsigned short

ws_row;

unsigned short

ws_col;

unsigned short

ws_xpixel;

unsigned short

ws_ypixel;

};

The winsize structure contains these fields:

ws_row ws_col ws_xpixel ws_ypixel

The number of rows, in characters, contained in the window

The number of columns, in characters, contained in the window

The horizontal size, in pixels, of the window (zero if the size is not known or if pixel values are not meaningful)

The vertical size, in pixels, of the window (zero if the size is not known or if pixel values are not meaningful)

If the function is called with a request value of TIOCSWINSZ and if a value in the winsize structure has changed since the last call, a SIGWINCH signal is sent to all processes in the foreground group.

Use From the Guardian Environment

A Guardian process cannot receive the SIGWINCH signal.

Use on Guardian Objects

The filedes parameter can specify a terminal file in /G.

RETURN VALUES

If the ioctl( ) function succeeds, it returns a value different from -1. The value returned depends on the device-control function. If an error occurs, the value -1 is returned, and errno is set to indicate the error.

ERRORS

If any of these conditions occurs, the ioctl( ) function sets errno to the corresponding value:

[EBADF]

[EFAULT]

The filedes parameter is not a valid descriptor.

The optional parameter is to be used as an address, but it points outside the process address space.

[EINTR]

[EINVAL]

A signal was caught during execution of the function.

The function was called for a device other than a terminal.

[ENETDOWN]

The filedes parameter specifies a file on a remote HP NonStop node (a remote

$ZTNT process), but communication with the remote node has been lost.

3

62 Hewlett-Packard Company 527186-003

System Functions (f - i) ioctl(2)

[ENOTSUP] The request parameter specifies an operation that is not supported on the device specified by the filedes parameter.

[ENOTTY] The device parameter is not associated with a character-special device, or the specified request does not apply to the type of object that descriptor device references.

[ENXIO] No such device or address exists.

[EOPNOTSUPP]

Operation not supported on socket. The type of socket (address family or protocol) does not support the requested operation.

[EWRONGID] One of these conditions occurred:

The process attempted an input or output operation on an input/output process (such as a terminal server process) that has failed or is in the down state.

The processor for the disk process of the specified file failed during an input or output operation, and takeover by the backup process occurred.

The open file descriptor has migrated to a new processor, but the new processor lacks a resource or system process needed for using the file descriptor.

The file descriptor specified by the filedes parameter can only be closed.

For all other error conditions, errno is set to the appropriate Guardian file-system error number.

See the Guardian Procedure Errors and Messages Manual for more information about a specific

Guardian file-system error.

RELATED INFORMATION

Files: tty(7).

STANDARDS CONFORMANCE

The OSS version of this function does not conform to a published standard.

HP extensions to the XPG4 Version 2 specification are:

The errno values [EFAULT], [ENETDOWN], [ENOTSUP], [ENXIO], [EOPNOTSUPP], and [EWRONGID] can be returned.

527186-003 Hewlett-Packard Company 3

63

Section 4. System Functions (k - m)

This section contains reference pages for Open System Services (OSS) system function calls with names that begin with k through m. These reference pages reside in the cat2 directory and are sorted alphabetically by U.S. English conventions in this section.

527186-003 Hewlett-Packard Company 4

1

kill(2) OSS System Calls Reference Manual

NAME

kill - Sends a signal to a process or group of processes

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/types.h>

/* optional except for POSIX.1 */

#include <signal.h> int kill(

pid_t pid,

int signal);

PARAMETERS

pid signal

Specifies the process or group of processes to be sent a signal.

Specifies the signal. If the signal parameter has the value 0 (zero, the null signal), error checking is performed but no signal is sent. The null signal can be used to check the validity of the pid parameter.

DESCRIPTION

The kill( ) function sends the signal specified by the signal parameter to the process or group of processes specified by the pid parameter.

To send a signal to another process, at least one of the following must be true:

The real or effective user ID of the sending process must match the real or saved-set-user

ID of the receiving process.

The process is trying to send the SIGCONT signal to a process in the same session.

The calling process has appropriate privileges.

Processes can send signals to themselves.

Use on Guardian Objects

The kill( ) function cannot send signals to Guardian processes.

Use From the Guardian Environment

If called from a Guardian process, the actions of this function are undefined and errno is set to

[ENOTOSS].

Specifying the Target Process

The kill( ) function allows the calling process to send a signal to a specific group of processes.

The pid parameter specifies the group according to the following rules:

If the pid parameter is greater than 0 (zero), the signal specified by the signal parameter is sent to the process that has an OSS process ID (PID) equal to the value of the pid parameter.

If the pid parameter is equal to 0 (zero), the signal specified by the signal parameter is sent to all of the processes whose process group ID is equal to the process group ID of the sender and for which the process has permission to send the signal.

If the pid parameter is negative but not equal to -1, the signal specified by the signal parameter is sent to all of the processes whose process group ID is equal to the absolute value of the pid parameter and for which the process has permission to send the signal.

4

2 Hewlett-Packard Company 527186-003

System Functions (k - m) kill(2)

The POSIX.1 standard leaves unspecified the set of system processes that does not receive a signal when the kill( ) function is called with pid equal to 0, -1, or a negative number less than -1.

Applications in the HP implementation should therefore not depend on which system processes receive signals.

Safeguard Considerations

HP recommends that users not use Safeguard protection on OSS processes. However, if users do use Safeguard protection on OSS processes, the following constraints apply.

For unnamed processes, the Safeguard software applies additional protection if the special

UNNAMED process protection record exists. For signals whose default action is to terminate the process, the system checks the access control list associated with the UNNAMED protection record and sends the signal only if the caller has purge authority.

When authority is granted to send a signal to a group of unnamed processes, all group members receive the signal in one step if the sending process has authority to send signals to all the processes in the group. Otherwise, the signal is not sent to any member of the group.

For named processes, the Safeguard software applies additional protection if a protection record exists for the specific process name. For signals whose default action is to terminate the process, the system checks the access control list associated with the protection record and sends the signal to the process only if the caller has purge authority.

When the kill( ) function attempts to send a signal to a group that contains named processes, the signal is sent to the named members of the group one at a time; that is, not all in one step as with unnamed processes. Processes joining or leaving the group between sending the signal to the first process and sending the signal to the last process can therefore affect the result of the combined operation.

Guardian Process Deletion Messages

When an OSS process terminates, the system performs most of the Guardian process-termination sequence. One of the steps in that sequence is to check if a Guardian Process Deletion (-101) message needs to be sent. The Guardian MOM, GMOM, and ANCESTOR attributes of the process determine the need to send the message and the recipient of the message.

OSS processes normally have null values for these attributes and therefore do not cause Process

Deletion messages to be sent. If an OSS process is created using any of the following functions with nonnull values for MOM, GMOM, and ANCESTOR in its process_extension_def structure, a Process Deletion message is sent during termination:

tdm_fork( )

tdm_exec set of functions

tdm_spawn set of functions

If an OSS process uses the Guardian PROCESS_SETINFO_ procedure to set nonnull values for

MOM, GMOM, and ANCESTOR, a Process Deletion message is sent during termination.

See the Guardian Procedure Errors and Messages Manual for details on the Process Deletion message. See the PROCESS_SETINFO_ procedure in the Guardian Procedure Calls Reference

Manual for information on setting the MOM field.

Terminated Processes

The kill( ) function does not return an error when applied to any process that has terminated but whose process lifetime is not yet exhausted. However, the operation has no effect, because the process is already terminated. The termination wait status of the process is unaffected by the operation.

527186-003 Hewlett-Packard Company 4

3

kill(2) OSS System Calls Reference Manual

RETURN VALUES

Upon successful completion, the kill( ) function returns the value 0 (zero). Otherwise, the value

-1 is returned, errno is set to indicate the error, and no signal is sent.

ERRORS

If any of the following conditions occurs, the kill( ) function sets errno to the corresponding value:

[EINVAL] The value in the signal parameter is an invalid or unsupported signal number.

[ENOTOSS] The calling process was not an OSS process. The kill( ) function cannot be used from the Guardian environment.

[EPERM]

[ESRCH]

The process does not have permission to send the signal to any receiving process.

No process or process group can be found corresponding to that specified by the

pid parameter.

RELATED INFORMATION

Functions: getpid(2), setpgid(2), setsid(2), sigaction(2), signal(3).

STANDARDS CONFORMANCE

The POSIX standards leave some features to the implementing vendor to define. The following features are affected in the HP implementation:

The mechanism that grants a process the appropriate privileges to send signals is described under DESCRIPTION.

The POSIX.1 standard leaves unspecified the set of system processes that does not receive a signal when the kill( ) function is called with pid equal to 0 (zero), -1, or a negative number less than -1. Applications in the HP implementation should therefore not depend on which system processes receive signals.

Additional restrictions are imposed by the Safeguard security mechanism on the sending of signals. See Safeguard Considerations.

The following are HP extensions to the XPG4 Version 2 specification:

Safeguard considerations

The ability to send signals to named processes

The error [ENOTOSS]

4

4 Hewlett-Packard Company 527186-003

System Functions (k - m) link(2)

NAME

link - Creates an additional directory entry for an existing file on the current fileset

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <unistd.h> int link(

const char *path1,

const char *path2);

PARAMETERS

path1 path2

Points to the pathname of an existing file.

If any component of the path1 parameter refers to a symbolic link, the link is traversed and pathname resolution continues.

Points to the pathname for the directory entry to be created.

If any component of the path2 parameter refers to a symbolic link, the link is traversed and pathname resolution continues.

If the final component of the path2 parameter refers to an existing entity, the call fails and errno is set to [EEXIST].

DESCRIPTION

The link( ) function creates an additional hard link (directory entry) for an existing file. Both the old and the new link share equal access rights to the underlying file. The link( ) function atomically creates a new link for the existing file and increments the link count of the file by 1.

The pathnames pointed to by both the path1 and path2 parameters must reside on the same fileset. If this is not the case, errno is set to [EXDEV].

The path1 parameter must not name a directory; a hard link to a directory cannot be created.

Attempting to create a link to a directory fails. The value -1 is returned and errno is set to

[EPERM].

Attempting to create a link to /dev/tty or /dev/null or attempting to create a link in the root directory of an OSS fileset to a file named lost+found fails and causes errno to be set to [EPERM].

The calling process requires the following:

Execute (search) permission on the directory containing the existing file.

Execute (search) and write permission on the directory into which the link is being added.

Upon successful completion, the link( ) function marks the st_ctime field of the file for update and marks the st_ctime and st_mtime fields of the directory containing the new entry for update.

527186-003 Hewlett-Packard Company 4

5

link(2) OSS System Calls Reference Manual

Use From the Guardian Environment

The link( ) function is one of a set of functions that have the following effects when the first of them is called from the Guardian environment:

Two Guardian file system file numbers (not necessarily the next two available) are allocated for the root directory and the current working directory. These file numbers cannot be closed by calling the Guardian FILE_CLOSE_ procedure.

The current working directory is assigned from the VOLUME attribute of the Guardian environment =_DEFAULTS DEFINE.

The use of static memory by the process increases slightly.

These effects occur only when the first of the set of functions is called. The effects are not cumulative.

Use on Guardian Objects

Attempting to create a link to a Guardian file (that is, a file within the /G file system) fails and causes errno to be set to [EINVAL].

RETURN VALUES

Upon successful completion, the link( ) function returns the value 0 (zero). If the link( ) function fails, the value -1 is returned, no link is created, and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the link( ) function sets errno to the corresponding value:

[EACCES]

[EEXIST]

[EFAULT]

[EFSBAD]

[EINVAL]

[EIO]

[ELOOP]

The requested link requires writing in a directory with a mode that denies write permission, or a component of the pathname pointed to by either the path1 or

path2 parameter denies search permission.

The link named by the path2 parameter already exists.

Either the path1 or path2 parameter is an invalid address.

The fileset catalog for one of the filesets involved in the operation is corrupt.

The call attempted to create a link to a Guardian file (that is, a file in /G or in any directory within /G).

An input or output error occurred. The device holding the file might be in the down state, or both processors that provide access to the device might have failed.

Too many symbolic links were encountered in translating either the path1 or

path2 parameter.

[EMLINK] The number of links to the file specified by the path1 parameter would exceed the maximum permitted. The pathconf( ) function can be called to obtain the configured limit.

[ENAMETOOLONG]

One of the following is too long:

The pathname pointed to by the path1 parameter

The pathname pointed to by the path2 parameter

4

6 Hewlett-Packard Company 527186-003

System Functions (k - m) link(2)

A component of the pathname pointed to by the path1 parameter

A component of the pathname pointed to by the path2 parameter

The intermediate result of pathname resolution when a symbolic link is part of the path1 or path2 parameter

The pathconf( ) function can be called to obtain the applicable limits.

[ENOENT] One of the following is true:

The file specified by the path1 parameter does not exist.

The path1 or path2 parameter is an empty string.

The path1 parameter names a symbolic link, but the file to which it refers does not exist.

The path1 or path2 parameter specifies a file on a remote HP NonStop node but communication with the remote node has been lost.

[ENOROOT] One of the following conditions exists:

The root fileset of the local node (fileset 0) is not in the STARTED state.

The current root fileset for the specified file is unavailable. The OSS name server for the fileset might have failed.

The specified file is on a remote HP NonStop node and communication with the remote name server has been lost.

[ENOSPC] The directory in which the entry for the new link is being placed cannot be extended, because there is no space left on the fileset containing the directory.

[ENOTDIR] A component of either pathname prefix is not a directory.

[ENXIO] The fileset containing the client’s current working directory or root directory is not mounted.

[EOSSNOTRUNNING]

The program attempted an operation on an object in the OSS environment while a required system process was not running.

[EPERM] One of the following conditions occurred:

The file specified by the path1 parameter is a directory.

The call attempted to create a link in the root directory of an OSS fileset to a file called lost+found.

The call attempted to create a link to /dev/tty or /dev/null.

[EROFS]

[EXDEV]

The requested link requires writing to a directory on a read-only fileset.

The link specified by the path2 parameter and the file specified by the path1 parameter are on different filesets.

527186-003 Hewlett-Packard Company 4

7

link(2) OSS System Calls Reference Manual

RELATED INFORMATION

Commands: ln(1).

Functions: unlink(2).

STANDARDS CONFORMANCE

The POSIX standards leave some features to the implementing vendor to define. The following features are affected in the HP implementation:

The link( ) function is not supported between filesets.

The link( ) function is not supported for directories.

The following are HP extensions to the XPG4 Version 2 specification:

The errors [EFAULT], [EFSBAD], [EINVAL], [EIO], [ENOROOT], [ENOTDIR],

[ENXIO], and [EOSSNOTRUNNING] can be returned.

4

8 Hewlett-Packard Company 527186-003

System Functions (k - m) listen(2)

NAME

listen - Listens for socket connections and limits the backlog of incoming connections

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/socket.h> int listen(

int socket,

int backlog

);

PARAMETERS

socket backlog

Specifies the file descriptor for the socket.

Specifies the maximum number of outstanding connections. The affect of this parameter varies according to the connection type and the stack implementation in use. Refer to the DESCRIPTION section of this reference page for more information.

DESCRIPTION

The listen( ) function marks a connection-oriented socket as accepting connections, and limits the number of outstanding connections in the socket’s queue to the value specified by the back-

log parameter.

For AF_INET sockets using conventional TCP/IP, a backlog parameter value of less than or equal to 0 allows the socket to accept the number of connections configured for the TCP-

LISTEN-QUE-MIN parameter of the transport process. These values can allow up to 5 connections (the default value for TCP-LISTEN-QUE-MIN).

For AF_INET or AF_INET6 sockets using parallel library TCP/IP or TCP/IPv6, a backlog parameter value of less than or equal to 0 is ignored. The maximum number of pending connections is always 5.

For AF_UNIX sockets, a backlog parameter value of less than or equal to 0 makes the socket refuse any connections. Subsequent attempts to connect to the socket fail and errno is set to

[ECONNREFUSED].

RETURN VALUES

Upon successful completion, the listen( ) function returns the value 0 (zero). Otherwise, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the listen( ) function sets errno to the corresponding value:

[EBADF] The socket parameter is not a valid file descriptor.

[ECONNRESET]

One of the following conditions occurred:

The transport-provider process for this socket is no longer available.

The TCP/IP subsystem for this socket is no longer available.

The connection was forcibly closed by the peer socket.

The socket can only be closed.

527186-003 Hewlett-Packard Company 4

9

listen(2) OSS System Calls Reference Manual

[EDESTADDRREQ]

The socket is not bound to a local address, and the protocol does not support listening on an unbound socket.

[EINVAL] One of the following conditions occurred:

The socket is already connected.

The socket has been shut down.

[ENOBUFS] There was not enough buffer space available to complete the call. A retry at a later time may succeed.

[ENOMEM] Required memory resources were not available. A retry at a later time may succeed.

[ENOTSOCK] The socket parameter does not refer to a socket.

[EOPNOTSUPP]

The socket specified by the socket parameter is not a type that supports the

listen( ) function.

RELATED INFORMATION

Functions: accept(2), connect(2), socket(2).

STANDARDS CONFORMANCE

The following are HP extensions to the XPG4 specification:

The errno value [ECONNRESET] can be returned when the transport provider process is unavailable.

The behavior when the backlog parameter is 0 (zero) is defined.

4

10 Hewlett-Packard Company 527186-003

System Functions (k - m) lseek(2)

NAME

lseek - Sets file offset for read or write operation

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/types.h>

/* optional except for POSIX.1 */

#include <unistd.h> off_t lseek(

int filedes,

off_t offset,

int whence);

PARAMETERS

filedes offset whence

Specifies an open file descriptor obtained from a successful call to the accept( ),

creat( ), dup( ), dup2( ), fcntl( ), open( ), pipe( ), socket( ), or socketpair( ) function.

Specifies a value, in bytes, that is used with the whence parameter to set the file pointer. A negative value causes seeking in the reverse direction.

Specifies how to interpret the offset parameter in setting the file pointer associated with the filedes parameter. Values for the whence parameter are:

SEEK_CUR

Sets the file pointer to its current location plus the value of the

offset parameter.

SEEK_END

Sets the file pointer to the size of the file plus the value of the

offset parameter.

SEEK_SET

Sets the file pointer to the value of the offset parameter.

DESCRIPTION

The lseek( ) function sets the file offset for the open file specified by the filedes parameter. The

whence parameter determines how the offset is to be interpreted.

The lseek( ) function allows the file offset to be set beyond the end of existing data in the file. If data is later written at this point, subsequent reading of data in the gap returns bytes with the value 0 (zero) until data is actually written into the gap.

The lseek( ) function does not, by itself, extend the size of the file.

RETURN VALUES

Upon successful completion, the resulting pointer location, measured in bytes from the beginning of the file, is returned. For FIFOs, pipes, and character special files, 0 (zero) is returned. For character special files, errno is not set.

If the lseek( ) function fails, the file offset remains unchanged, a value of -1 cast to the type off_t is returned, and errno is set to indicate the error.

ERRORS

If any of these conditions occurs, the file offset remains unchanged, and the lseek( ) function sets

errno to the corresponding value:

[EBADF] The filedes parameter is not an open file descriptor.

527186-003 Hewlett-Packard Company 4

11

lseek(2) OSS System Calls Reference Manual

[EINVAL] One of these conditions exists:

The whence parameter is an invalid value, or the resulting file offset would be an invalid value (that is, a value greater than 2 gigabytes or less than 0 [zero]).

The filedes parameter refers to a file (other than a pipe, FIFO, or directory) on which seeking cannot be performed.

[EISDIR] The filedes parameter refers to an OSS directory.

[EISGUARDIAN]

The value used for the filedes parameter is appropriate only in the Guardian environment.

[ESPIPE] The filedes parameter refers to a pipe, FIFO, or socket.

[EWRONGID] One of these conditions occurred:

The process attempted an operation through an operating system input/output process (such as a terminal server process) that has failed or is in the down state.

The processor for the disk process of the specified file failed during an input or output operation, and takeover by the backup process occurred.

The open file descriptor has migrated to a new processor, but the new processor lacks a resource or system process needed for using the file descriptor.

The file descriptor specified by the filedes parameter can only be closed.

For all other error conditions, errno is set to the appropriate Guardian file-system error number.

See the Guardian Procedure Errors and Messages Manual for more information about a specific

Guardian file-system error.

RELATED INFORMATION

Functions: fcntl(2), fseek(3), open(2), read(2), write(2).

STANDARDS CONFORMANCE

The POSIX standards leave some features to the implementing vendor to define. These features are affected in the HP implementation:

If the lseek( ) function is called for a pipe or FIFO, the errno value [ESPIPE] is returned.

If the lseek( ) function is called for a character special file, no errno value is returned.

If the lseek( ) function is called for any other device on which seeking cannot be performed, the operation fails, and errno is set to [EINVAL].

HP extensions to the XPG4 Version 2 specification are:

The errno values [EINVAL], [EISDIR], [EISGUARDIAN], and [EWRONGID] can be returned.

4

12 Hewlett-Packard Company 527186-003

System Functions (k - m) lstat(2)

NAME

lstat - Provides information about a symbolic link or any file

LIBRARY

G-series native Guardian processes: system library

G-series native OSS processes: system library

H-series native Guardian processes: implicit libraries

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/stat.h> int lstat(

const char *path,

struct stat *buffer);

PARAMETERS

path buffer

Points to the pathname of a file. If used for a symbolic link, then the path parameter points to the pathname of the symbolic link identifying the file.

Points to a stat structure, into which information is placed about the file.

DESCRIPTION

The lstat( ) function obtains information about the symbolic link whose name is pointed to by the

path parameter or about any file pointed to by the path parameter.

The lstat( ) function is like the stat( ) or fstat( ) function, except that lstat( ) returns information about the link, while the stat( ) and fstat( ) functions return information about the file that the link refers to.

Read, write, or execute permission for the named file is not required, but all directories listed in the pathname leading to the file must be searchable.

The file information is written to the area specified by the buffer parameter, which is a pointer to a stat structure with the following definition from the sys/stat.h header file:

struct stat { dev_t st_dev; ino_t st_ino; mode_t st_mode; nlink_t st_nlink; char filler_1[2]; uid_t st_uid; gid_t st_gid; char filler_2[4]; dev_t st_rdev; off_t st_size; time_t st_atime; time_t st_mtime; time_t st_ctime; int64_t reserved[3];

};

For symbolic links to local OSS objects, the st_mode and st_size fields are valid and the other fields in the structure are undefined. For symbolic links that resolve to files in /E, the st_dev,

st_ino, st_atime, st_mtime, and st_ctime fields are defined as described in this reference page.

For files other than a symbolic link, the lstat( ) function sets the st_size field of the stat structure to the length in characters of the absolute pathname resulting from the resolution of the name

527186-003 Hewlett-Packard Company 4

13

lstat(2) OSS System Calls Reference Manual

pointed to by path. For a symbolic link, the lstat( ) function sets the st_size field of the stat structure to the length in characters of the link name used as the pathname pointed to by path (not including the null terminator).

The lstat( ) function also sets the st_mode field to indicate the file type.

The lstat( ) function updates any time-related fields associated with the file before writing into the stat structure, unless it is a read-only fileset. Time-related fields are not updated for read-only

OSS filesets.

The fields in the stat structure have the following meanings and content:

st_dev

OSS device identifier for a fileset.

Values for local OSS objects are listed in the following table. Values for local

Guardian objects are described in Use on Guardian Objects, and values for remote Guardian or OSS objects are described in Use on Remote Objects, later in this reference page.

st_ino

For

Regular file

Directory

FIFO

AF_UNIX socket

Contains

ID of device containing directory entry

ID of device containing directory

ID of special fileset for pipes

ID of device containing the fileset in which the socket file was created

ID of device containing directory entry

ID of device containing directory entry

/dev/null

/dev/tty

File serial number (inode number). The file serial number and OSS device identifier uniquely identify a regular OSS file within an OSS fileset.

Values for OSS objects are listed in the following table. Values for Guardian objects are described in Use on Guardian Objects, later in this reference page.

For

Regular file

Directory

FIFO

AF_UNIX socket

Contains

File serial number (unique)

File serial number (unique)

File serial number (unique)

File serial number of the socket file

(unique)

File serial number (unique)

File serial number (unique)

/dev/null

/dev/tty

The st_ino value for all node entries in /E (including the entry for the logical link from the local node name to the root fileset on the local node) is the value for the root fileset on the corresponding node. If normal conventions are followed, this value is always 0 (zero), so entries in /E appear to be nonunique.

Values for objects on remote nodes are unique only among the values for objects within the same fileset on that node.

4

14 Hewlett-Packard Company 527186-003

System Functions (k - m) lstat(2) st_mode st_nlink

File mode. The following bits are ORed into the st_mode field:

S_IFMT

File type. This field can contain one of the following values:

S_IFCHR

S_IFDIR

S_IFIFO

Character special file.

Directory.

FIFO.

S_IFREG

Regular file.

S_IFSOCK

Socket.

For an AF_UNIX socket, the user permissions from the inode for the socket are returned for the permission bits. The access flags are also returned from the inode.

S_NONSTOP Regular file in the OSS file system protected by disk process checkpointing. (Files in /G cannot have this bit set.)

When set, indicates that return from a write operation does not occur until both the primary and backup disk processes have the data (thereby protecting the data against a single point of failure).

OSS file-system data caching is disabled for write operations on files for which this bit is set. Performance is slower than when caching is used, but data integrity protection increases. Performance is faster than when the O_SYNC bit in the open( ) function oflag parameter is used, but data integrity protection is less than that provided by O_SYNC use.

S_IRWXG

Group class

S_IRWXO

Other class

S_IRWXU

S_ISGID

Owner class

Set group ID on execution

S_ISUID

Set user ID on execution

S_ISVTX

Sticky bit; used only for directories (not ORed for files in /G, the

Guardian file system)

Values for Guardian objects are described in Use on Guardian Objects, later in this reference page.

Number of links.

Values for OSS objects are listed in the following table. Values for Guardian objects are described in Use on Guardian Objects, later in this reference page.

527186-003 Hewlett-Packard Company 4

15

lstat(2) OSS System Calls Reference Manual st_uid st_gid st_rdev

For

Regular file

Directory

FIFO

AF_UNIX socket

/dev/null

/dev/tty

Contains

Number of links to the file

Number of links to the directory

Number of links to the file

Number of links to the socket file

Number of links to the file

Number of links to the file

User ID.

Values for OSS objects are listed in the following table. Values for Guardian objects are described in Use on Guardian Objects, later in this reference page.

For

Regular file

Directory

FIFO

AF_UNIX socket

/dev/null

/dev/tty

Contains

User ID of the file owner

User ID of the file owner

User ID of the file owner

User ID of the creator of the socket file

User ID of the super ID

User ID of the super ID

Group ID.

Values for OSS objects are listed in the following table. Values for Guardian objects are described in Use on Guardian Objects, later in this reference page.

For

Regular file

Directory

FIFO

AF_UNIX socket

/dev/null

/dev/tty

Contains

Group ID of the file group

Group ID of the file group

Group ID of the file group

Group ID of the creater of the socket file

Group ID of the super ID

Group ID of the super ID

Remote device ID.

Values for OSS objects are listed in the following table. Values for Guardian objects are described in Use on Guardian Objects, later in this reference page.

4

16 Hewlett-Packard Company 527186-003

System Functions (k - m) lstat(2) st_size st_atime st_mtime

For

Regular file

Directory

FIFO

AF_UNIX socket

/dev/null

/dev/tty

Contains

Undefined

Undefined

Undefined

0 (zero)

Undefined

ID of the device

File size.

Values for OSS objects are listed in the following table. Values for Guardian objects are described in Use on Guardian Objects, later in this reference page.

For

Regular file

Directory

FIFO

AF_UNIX socket

/dev/null

/dev/tty

Contains

Size of the file in bytes

4096

0 (zero)

0 (zero)

0 (zero)

0 (zero)

Access time.

Values for OSS objects are listed in the following table. Values for Guardian objects are described in Use on Guardian Objects, later in this reference page.

For

Regular file

Directory

FIFO

AF_UNIX socket

/dev/null

/dev/tty

Contains

Time of the last access

Time of the last access

Time of the last access

Value retrieved from the inode

Current time

Composite value of the times of all openers of the file

For the /E entry of the local node, the value is the time of the most recent mounting of the root fileset.

Modification time.

Values for OSS objects are listed in the following table. Values for Guardian objects are described in Use on Guardian Objects, later in this reference page.

527186-003 Hewlett-Packard Company 4

17

lstat(2) OSS System Calls Reference Manual st_ctime

For

Regular file

Directory

FIFO

AF_UNIX socket

/dev/null

/dev/tty

Contains

Time of the last data modification

Time of the last modification

Time of the last data modification

Value retrieved from the inode

Current time

Composite value of the times of all openers of the file

For the /E entry of the local node, the value is the time of the most recent mounting of the root fileset.

Status change time.

Values for OSS objects are listed in the following table. Values for Guardian objects are described in Use on Guardian Objects, later in this reference page.

For

Regular file

Directory

FIFO

AF_UNIX socket

/dev/null

/dev/tty

Contains

Time of the last file status change

Time of the last file status change

Time of the last file status change

Value retrieved from the inode

Current time

Composite value of the times of all openers of the file

For the /E entry of the local node, the value is the time of the most recent mounting of the root fileset.

Use on Guardian Objects

The lstat( ) function can be used like the stat( ) or fstat( ) function on files in /G, but symbolic links cannot be created in /G.

The st_dev and st_ino fields of the stat structure do not uniquely identify Guardian files (files in

/G).

The st_dev field is unique for /G, for each disk volume, and for each Telserv process (or other process of subdevice type 30), because each of these is a separate fileset.

The S_ISGUARDIANOBJECT macro can indicate whether an object is a Guardian object when the st_dev field is passed to the macro. The value of the macro is TRUE if the object is a

Guardian object and FALSE otherwise.

The st_ino field is a nonunique encoding of the Guardian filename.

The st_rdev field contains a minor device number for each ptyn entry in /G/ztnt/, representing each Telserv process subdevice.

The st_size field of an EDIT file (file code 101) is the actual (physical) end of file, not the number of bytes in the file. For directories, st_size is set to 4096.

When an OSS function is called for a Guardian EDIT file, the st_mtime field is set to the last modification time. The st_atime field indicates the last time the file was opened, and the

st_ctime field is set equal to st_mtime. No other time-related fields are updated by OSS functions.

4

18 Hewlett-Packard Company 527186-003

System Functions (k - m) lstat(2)

The st_ctime and st_atime fields for Guardian regular disk files (except for EDIT files) are updated by OSS function calls, not by Guardian procedure calls.

The time fields for /G, /G/vol, and /G/vol/subvol always contain the current time.

When the path parameter points to the name of a Guardian process that is not a process of subtype 30, the lstat( ) function call fails. The value -1 is returned and errno is set to [ENOENT].

The lstat( ) function always returns access modes of "d---------" when the path parameter points to a Guardian subvolume that has a reserved name beginning with "ZYQ". The other access modes reported for files in /G vary according to the file type.

The following table shows the mapping between Guardian files and their corresponding file types described in the st_mode field.

Table 4

1. Guardian File Type Mappings

Example in /G

Guardian

File Type st_mode

File Type Permissions

/G

vol

N/A

Disk volume

vol/subvol Subvolume

vol/subvol/fileid Disk file

vol/#123

ztnt ztnt/#pty0001 vol1/zyq00001

Directory

Directory

Directory

Regular file r-xr-xr-x rwxrwxrwx rwxrwxrwx

See following text

Temporary disk file Regular file See following text

Subtype 30 process Directory

Subtype 30 process with qualifier

--x--x--x

Character special rw-rw-rw-

Subvolume Directory ---------

A Guardian file classified as a directory is always owned by the super ID.

Guardian permissions are mapped as follows:

A Guardian network or any user permission is mapped to an OSS other permission.

A Guardian community or group user permission is mapped to an OSS group permission.

A Guardian user or owner permission is mapped to an OSS owner permission.

A Guardian super ID permission is an OSS super ID permission.

Guardian read permission is mapped to OSS read permission.

Guardian write permission is mapped to OSS write permission.

Guardian execute permission is mapped to OSS execute permission.

Guardian purge permission is ignored.

Users are not allowed read access to Guardian processes.

OSS file permissions are divided into three groups (owner, group, and other) of three permission bits each (read, write, and execute). Note that the OSS permission bits do not distinguish between remote and local users as Guardian security does; local and remote users are treated alike.

527186-003 Hewlett-Packard Company 4

19

lstat(2) OSS System Calls Reference Manual

Use on Remote Objects

The content of the st_dev field of the stat structure is unique for each node in /E because each of these is a separate fileset. Values for directories within /E are the same as described for objects on the local HP NonStop node.

The S_ISEXPANDOBJECT macro can indicate whether an object in the /E directory is on a remote HP NonStop node when the st_dev field is passed to the macro. The value of the macro is TRUE if the object is on a remote HP NonStop node and FALSE otherwise.

Use From the Guardian Environment

The lstat( ) function can be used by a Guardian process when the process has been compiled using the #define _XOPEN_SOURCE_EXTENDED 1 feature test macro or an equivalent compiler command option.

The lstat( ) function belongs to a set of functions that have the following effects when the first of them is called from the Guardian environment:

Two Guardian file system file numbers (not necessarily the next two available) are allocated for the root directory and the current working directory. These file numbers cannot be closed by calling the Guardian FILE_CLOSE_ procedure.

The current working directory is assigned from the VOLUME attribute of the Guardian environment =_DEFAULTS DEFINE.

The use of static memory by the process increases slightly.

These effects occur only when the first of the set of functions is called. The effects are not cumulative.

RETURN VALUES

Upon successful completion, the value 0 (zero) is returned. Otherwise, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the lstat( ) function sets errno to the corresponding value:

[EACCES]

[EFAULT]

Search permission is denied for a component of the pathname pointed to by the

path parameter.

Either the buffer parameter or the path parameter points to a location outside of the allocated address space of the process.

[EFSBAD]

[EIO]

The program attempted an operation involving a fileset with a corrupted fileset catalog.

An input or output error occurred. The device holding the file might be in the down state, or both processors that provide access to the device might have failed.

[ELOOP] Too many symbolic links were encountered in translating path.

[ENAMETOOLONG]

One of the following is too long:

The pathname pointed to by the path parameter

4

20 Hewlett-Packard Company 527186-003

System Functions (k - m) lstat(2)

A component of the pathname pointed to by the path parameter

The intermediate result of pathname resolution when a symbolic link is part of the path parameter

The pathconf( ) function can be called to obtain the applicable limits.

[ENOENT] One of the following conditions exists:

The file specified by the path parameter does not exist.

path points to an empty string.

The specified pathname cannot be mapped to a valid Guardian filename.

The specified pathname points to the name of a Guardian process that is not of subtype 30.

The path parameter specifies a file on a remote HP NonStop node but communication with the remote node has been lost.

[ENOROOT] The program attempted an operation while the root fileset was unavailable.

[ENOTDIR] A component of the pathname specified by the path parameter is not a directory.

[ENXIO] An invalid device or address was specified during an input or output operation on a special file. One of the following events occurred:

A device was specified that does not exist, or a request was made beyond the limits of the device.

The fileset containing the requestor’s current working directory or root directory is not mounted. This error can occur after failure and restart of an OSS name server process until the fileset has been repaired and remounted.

[EOSSNOTRUNNING]

The program attempted an operation on an object in the OSS environment while a required system process was not running.

RELATED INFORMATION

Functions: chmod(2), chown(2), fstat(2), open(2), pipe(2), readlink(2), stat(2), symlink(2),

utime(2).

STANDARDS CONFORMANCE

The following are HP extensions to the XPG4 Version 2 specification:

The errno values [EFAULT], [EFSBAD], [ENOROOT], [ENXIO], and [EOSSNO-

TRUNNING] can be returned by the lstat( ) function.

The HP implementation does not issue the [EOVERFLOW] value for errno.

527186-003 Hewlett-Packard Company 4

21

mkdir(2) OSS System Calls Reference Manual

NAME

mkdir - Creates a directory

LIBRARY

G-series native Guardian processes: system library

G-series native OSS processes: system library

H-series native Guardian processes: implicit libraries

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/types.h>

/* optional except for POSIX.1 */

#include <sys/stat.h> int mkdir(

const char *path,

mode_t mode);

PARAMETERS

path mode

Points to the pathname for the new directory.

If any component of the path parameter refers to a symbolic link, the link is traversed and pathname resolution continues.

If the final component of the path parameter refers to an existing entity, the call fails and errno is set to [EEXIST].

Specifies the mask for the read, write, and search/execute (RWX) flags for owner, group, and others. Also specifies the file type flags for the directory.

The permission bits are set according to the value of this parameter modified by the process’s file creation mask (see the umask(2) reference page). The value of this parameter is constructed by logically ORing flags that are defined in the

sys/stat.h header file.

The file type flags are described in DESCRIPTION.

DESCRIPTION

The mkdir( ) function creates a new directory with the following attributes:

The owner ID is set to the effective user ID of the calling process. Directories within /G

(the Guardian file system) are the exception; for them, the owner ID is set to 65535 (the super ID).

The group ID is set to the group ID of the parent directory if the S_ISGID flag is set in the parent directory; otherwise, the group ID is set to the effective group ID of the calling process. Directories within /G (the Guardian file system) are the exception; for them, the group ID is set to 255.

The permission bits are set according to the value of the mode parameter modified by the process’s file creation mask (see the umask(2) reference page). The value of this parameter is constructed by logically ORing flags that are defined in the sys/stat.h header file.

Directories within /G (the Guardian file system) are the exception; for them, all the permission bits ("rwxrwxrwx") are automatically set.

The new directory is empty except for . (dot) and . . (dot-dot).

To execute the mkdir( ) function, a process must have search permission for the parent directory of the directory pointed to by the path parameter and write permission in the parent directory of the path directory.

4

22 Hewlett-Packard Company 527186-003

System Functions (k - m) mkdir(2)

The mkdir( ) function cannot create a directory named /dev, /dev/tty, or /dev/null in the root directory of the OSS file system. The mkdir( ) function cannot create a directory named

lost+found in the root directory of an OSS fileset. If these directories are missing from the system, such a function call fails and sets errno to the value [EPERM]. When these directories already exist (the normal case), errno is set to [EEXIST].

If bits in the mode parameter other than the file permission bits, S_ISVTX, S_IFDIR, or

S_NONSTOP are set, mkdir( ) fails and sets errno to [EINVAL].

Upon successful completion, the mkdir( ) function marks the st_atime, st_ctime, and st_mtime fields of the directory for update and marks the st_ctime and st_mtime fields of the new directory’s parent directory for update.

Use on Guardian Objects

The mkdir( ) function succeeds within /G (the Guardian file system) only when creating a Guardian subvolume that is exactly three directories under the root (for example, /G/vol/subvol). This

Guardian subvolume must be empty. If the subvolume is not empty, errno is set to [EEXIST].

When the call succeeds, the resulting directory (subvolume) is owned by the super ID.

File Type Flags

The file type flags that can be logically ORed into the value specified in the mode parameter are as follows:

S_IFDIR

S_ISVTX

Directory in the OSS file system or empty subvolume in /G, the Guardian file system.

Sticky bit; used only for directories (cannot be used for files in /G, the Guardian file system).

When set, a user can remove files from the directory only if the user either:

Has write permission for the directory and is the owner of either the directory or the file being removed

Has appropriate privileges

S_NONSTOP Directory in the OSS file system protected by disk process checkpointing. (Files in /G cannot have this flag set.)

When set, this flag indicates that return from a write operation does not occur until both the primary and backup disk processes have the data (thereby protecting the data against a single point of failure).

OSS file-system data caching is disabled for write operations on files for which this flag is set. Performance is slower than when caching is used, but data integrity protection increases. Performance is faster than when the O_SYNC flag in the oflag parameter of the open( ) function is used, but data integrity protection is less than that provided by O_SYNC use.

Use From the Guardian Environment

The mkdir( ) function is one of a set of functions that have the following effects when the first of them is called from the Guardian environment:

Two Guardian file system file numbers (not necessarily the next two available) are allocated for the root directory and the current working directory. These file numbers cannot be closed by calling the Guardian FILE_CLOSE_ procedure.

527186-003 Hewlett-Packard Company 4

23

mkdir(2) OSS System Calls Reference Manual

The current working directory is assigned from the VOLUME attribute of the Guardian environment =_DEFAULTS DEFINE.

The use of static memory by the process increases slightly.

These effects occur only when the first of the set of functions is called. The effects are not cumulative.

RETURN VALUES

Upon successful completion, the mkdir( ) function returns the value 0 (zero). If the function call fails, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the directory is not created and the mkdir( ) function sets errno to the corresponding value:

[EACCES]

[EEXIST]

[EFAULT]

[EFSBAD]

[EINVAL]

Creating the requested directory requires writing in a directory with a mode that denies write permission, or search permission is denied on the parent directory of the directory to be created.

The named file already exists.

The path parameter is an invalid address.

The fileset catalog for one of the filesets involved in the operation is corrupt.

One of the following conditions exists:

The program supplied an invalid value for the mode parameter.

The pathname supplied in the call attempts to create a directory in the

Guardian file system, but the pathname cannot be mapped to a valid

Guardian subvolume name.

[EIO] A physical input or output error has occurred.

[ELOOP] Too many symbolic links were encountered in translating path.

[ENAMETOOLONG]

One of the following is too long:

The pathname pointed to by the path parameter

A component of the pathname pointed to by the path parameter

The intermediate result of pathname resolution when a symbolic link is part of the path parameter

The pathconf( ) function can be called to obtain the applicable limits.

[ENOENT] One of the following is true:

A component of the prefix of the pathname pointed to by the path parameter does not exist.

The path parameter points to an empty string.

The path parameter names a symbolic link, but the file to which it refers does not exist.

4

24 Hewlett-Packard Company 527186-003

System Functions (k - m) mkdir(2)

The path parameter specifies a file on a remote HP NonStop node but communication with the remote node has been lost.

[ENOROOT] One of the following conditions exists:

The root fileset of the local node (fileset 0) is not in the STARTED state.

The current root fileset for the specified file is unavailable. The OSS name server for the fileset might have failed.

The specified file is on a remote HP NonStop node and communication with the remote name server has been lost.

[ENOSPC] The fileset does not contain enough space to hold the contents of the new directory or to extend the parent directory of the new directory.

[ENOTDIR] A component of the pathname prefix is not a directory.

[ENXIO] The fileset containing the client’s current working directory or root directory is not mounted.

[EOSSNOTRUNNING]

The program attempted an operation on an object in the OSS environment while a required system process was not running.

[EPERM] One of the following conditions is true:

The call attempted to create a directory named lost+found in the root directory of an OSS fileset, or attempted to create a directory named

/dev, /dev/tty, or /dev/null in the the root directory of the OSS file system.

The call attempted to create a subvolume directory in /G (the Guardian file system) that has a name beginning with ZYQ.

The call attempted to create a file in the /E directory.

[EROFS] The named file resides on a read-only fileset.

RELATED INFORMATION

Functions: chmod(2), mknod(2), rmdir(2), umask(2).

Commands: chmod(1), mkdir(1).

STANDARDS CONFORMANCE

The POSIX standards leave some features to the implementing vendor to define. The following features are affected in the HP implementation:

If bits in the mode parameter other than the file permission bits, S_ISVTX, S_IFDIR, or

S_NONSTOP are set, mkdir( ) fails and sets errno to [EINVAL].

The group ID is set to the group ID of the parent directory if the S_ISGID flag is set in the parent directory; otherwise, the group ID is set to the effective group ID of the calling process. Directories within /G (the Guardian file system) are the exception; for them, the group ID is set to 255.

The following are extensions to the XPG4 Version 2 specification:

The errno values [EFAULT], [EFSBAD], [EINVAL], [EIO], [ENOROOT], [ENXIO],

[EOSSNOTRUNNING], and [EPERM] can be returned.

527186-003 Hewlett-Packard Company 4

25

mkdir(2) OSS System Calls Reference Manual

4

26 Hewlett-Packard Company 527186-003

System Functions (k - m) mknod(2)

NAME

mknod - Creates a file or assigns a pathname to a character special file

LIBRARY

G-series native Guardian processes: system library

G-series native OSS processes: system library

H-series native Guardian processes: implicit libraries

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/stat.h> int mknod(

const char *path,

mode_t mode,

dev_t device);

PARAMETERS

path mode

Specifies the pathname of the new file. If the final component of the path parameter names a symbolic link, the link is traversed and pathname resolution continues.

Specifies the file type, attributes, and access permissions. This parameter is constructed by logically ORing one file type value with any valid value for an attribute for a file of that type, and with any valid access permissions.

The following file type values are supported:

S_IFCHR

S_IFDIR

S_IFIFO

The file is a character special file.

The file is a directory special file.

The file is a FIFO special file.

S_IFREG

The file is a regular file.

Values other than S_IFIFO can be used only if the process has appropriate privileges.

The file type value S_IFBLK is not supported in the OSS file system. If

S_IFBLK is specified, the function call fails and errno is set to the value of

[EINVAL].

The following access permissions are supported:

S_IRGRP

S_IROTH

Read access by members of the group list

Read access by others

S_IRUSR

Read access by the owner of the file

S_IRWXG

Read, write, or execute (search) access by members of the group list

S_IRWXO

Read, write, or execute (search) access by others

S_IRWXU

Read, write, or execute (search) access by the owner of the file

527186-003 Hewlett-Packard Company 4

27

mknod(2) OSS System Calls Reference Manual

S_ISGID

S_ISUID

S_ISVTX

Set the group ID of the file upon execution of the file

Set the user ID of the file upon execution of the file

Restrict the deletion of files in a directory (ignored for other file types)

S_IWGRP

Write access by members of the group list

S_IWOTH

Write access by others

S_IWUSR

S_IXGRP

Write access by the owner of the file

Execute (search) access by members of the group list

S_IXOTH

S_IXUSR

Execute (search) access by others

Execute (search) access by the owner of the file

The following file attributes are supported:

S_NONSTOP For a regular file, setting this flag causes the following actions:

Disables file system caching

Returns control to a calling process only after the backup disk process has received checkpoint data for a write operation

device

Specifies the type of device on which the file is created. This hexadecimal value must be 0 (zero) unless the file type S_IFCHR is specified for the mode parameter. When S_IFCHR is specified, the following values are valid:

0x0000000300000000

The device is an infinite data source or data sink, such as

/dev/null.

0x0000000200000000

The device is a controlling terminal, such as /dev/tty.

Specifying any other value for the device parameter when S_IFCHR is specified for the mode parameter causes the function call to fail and errno to be set to

[EINVAL].

DESCRIPTION

The mknod( ) function creates a new special or regular file. Using the mknod( ) function to create file types other than FIFOs requires appropriate privileges.

For the mknod( ) function to finish successfully, a process must have search permission and write permission in the parent directory of the path parameter.

The new file has the following characteristics:

A file type as specified by the mode parameter.

An owner ID set to the effective user ID of the process.

4

28 Hewlett-Packard Company 527186-003

System Functions (k - m) mknod(2)

A group ID set to the effective group ID of the process or to the group ID of the parent directory of the file.

Access permission and attribute bits set according to the value of the mode parameter, as modified by the settings of the file mode creation mask for the process. Access permission and attribute bits are cleared when the corresponding file mode creation mask bits are set. (See the umask(2) reference page.)

Upon successful completion of the function call, the st_atime, st_ctime, and st_mtime fields of the file are marked for update. The st_ctime and st_mtime fields of the directory that contains the new entry are also marked for update.

Use From the Guardian Environment

The mknod( ) function can be used by a Guardian process when the process has been compiled using the #define _XOPEN_SOURCE_EXTENDED 1 feature-test macro or an equivalent compiler command option.

The mknod( ) function is one of a set of functions that have the following effects when the first of them is called from the Guardian environment:

Two Guardian file-system file numbers (not necessarily the next two available) are allocated for the root directory and the current working directory. These file numbers cannot be closed by calling the Guardian FILE_CLOSE_ procedure.

The current working directory is assigned from the VOLUME attribute of the Guardian environment =_DEFAULTS DEFINE.

The use of static memory by the process increases slightly.

These effects occur only when the first of the set of functions is called. The effects are not cumulative.

Use on Guardian Objects

When S_IFREG is specified for the mode parameter, the path parameter can be any valid version of the following:

/G/vol/subvol Where vol already exists. If vol does not exist, the function call fails and errno is set to the value of [EINVAL].

/G/vol/subvol/fileid

Where vol already exists and fileid specifies a regular disk file (an odd unstructured Enscribe file). If vol does not exist, the function call fails and errno is set to the value of [EINVAL].

If only /G/vol is specified, the function call fails and errno is set to the value of [EPERM].

When S_IFCHR is specified for the mode parameter, any specification for the path parameter that uses /G causes the function call to fail and errno to be set to [EPERM].

When S_IFDIR is specified for the mode parameter, a specification of /G/vol for the path parameter causes the function call to fail and errno to be set to [EINVAL].

If any other file type value is used for the mode parameter of a file in /G, the function call fails and errno is set to the value of [EINVAL].

The file access permissions S_ISUID, S_ISGID, and S_ISVTX are ignored when you are creating files in the Guardian file system.

527186-003 Hewlett-Packard Company 4

29

mknod(2) OSS System Calls Reference Manual

NOTES

Use the mkfifo( ) function instead of the mknod( ) function to create a FIFO when you need to port an application to a UNIX system that does not support XPG4 Version 2.

RETURN VALUES

Upon successful completion, the value 0 (zero) is returned. Otherwise, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the new file is not created and the mknod( ) function sets errno to the corresponding value:

[EACCES]

[EEXIST]

[EFAULT]

[EFSBAD]

[EINVAL]

A component of the pathname prefix denies search permission, or write permission is denied on the parent directory of the file to be created.

The named file exists.

The path parameter points outside the process’s allocated address space.

The fileset catalog for one of the filesets involved in the operation is corrupt.

One of the following conditions exists:

The value S_IFBLK was specified for the mode parameter.

A value other than 0 (zero) was specified for the device parameter when a value other than S_IFCHR was specified for the mode parameter.

An invalid value was specified for the device parameter when the value

S_IFCHR was specified for the mode parameter.

The mode parameter specifies a file type of S_IFDIR but the path parameter specifies a pathname of the form /G/vol.

The mode parameter specifies a file type of S_IFIFO but the path parameter specifies a pathname in /G (the Guardian file system).

[EIO] During an access of the file system, an I/O error occurred.

[ELOOP] Too many symbolic links were encountered in resolving the value of the path parameter.

[ENAMETOOLONG]

One of the following is too long:

The pathname pointed to by the path parameter

A component of the pathname pointed to by the path parameter

The intermediate result of pathname resolution when a symbolic link is part of the pathname pointed to by the path parameter

The pathconf( ) function can be called to obtain the applicable limits.

[ENOENT] One of the following conditions exists:

The named directory does not exist.

4

30 Hewlett-Packard Company 527186-003

System Functions (k - m) mknod(2)

The specified pathname is an empty string.

The specified pathname cannot be mapped to a valid Guardian filename.

The path parameter includes a symbolic link, but the file to which it refers does not exist.

The path parameter specifies a file on a remote HP NonStop node but communication with the remote node has been lost.

[ENOROOT] The root fileset (fileset 0) is not in the STARTED state.

[ENOSPC] The directory that would contain the new file cannot be extended, or the fileset is out of resources.

[ENOTDIR] A component of the pathname prefix is not a directory.

[ENXIO] The fileset containing the client’s working directory or effective root directory is not mounted.

[EOSSNOTRUNNING]

The program attempted an operation on an object in the OSS environment while a required system process was not running.

[EPERM] One of the following conditions exists:

The mode parameter specifies a file type other than S_IFIFO and the calling process does not have appropriate privileges.

The mode parameter specifies a file type of S_IFREG but the path parameter specifies a pathname of the form /G/vol.

The mode parameter specifies a file type of S_IFCHR but the path parameter specifies a pathname in /G (the Guardian file system).

The call attempted to create a file in the /E directory.

[EROFS] The directory in which the file is to be created is located on a read-only fileset.

RELATED INFORMATION

Functions: chmod(2), mkdir(2), mkfifo(3), open(2), umask(2), stat(2).

Commands: chmod(1), mkdir(1).

STANDARDS CONFORMANCE

The OSS file system does not support block special files. The file type S_IFBLK is therefore not valid.

The following are HP extensions to the XPG4 Version 2 specification:

The errno values [EFAULT], [EFSBAD], [ENOROOT], [ENXIO], and [EOSSNO-

TRUNNING] can be returned.

The file attribute S_NONSTOP is supported.

Behavior is defined when values for the mode parameter other than S_IFIFO are specified.

527186-003 Hewlett-Packard Company 4

31

mknod(2) OSS System Calls Reference Manual

Behavior is defined when values for the device parameter other than 0 (zero) are specified.

4

32 Hewlett-Packard Company 527186-003

System Functions (k - m) msgctl(2)

NAME

msgctl - Performs message control operations

LIBRARY

G-series native OSS processes: /G/system/sysnn/zossksrl

H-series OSS processes: /G/system/zdllnnn/zosskdll

SYNOPSIS

#include <sys/msg.h> int msgctl(

int msqid,

int cmd,

struct msqid_ds *buf);

PARAMETERS

msqid cmd

Specifies the message queue identifier.

Specifies the type of operation. The possible values for cmd and the operations they perform are as follows:

IPC_RMID

Removes the message queue identifier and deallocates its associated msqid_ds structure.

This is a restricted operation. The effective user ID of the calling process either must have appropriate privileges or must be equal to the value of the owner’s user ID (msg_perm.uid field) or the creator’s user ID (msg_perm.cuid field) in the associated

msqid_ds structure.

IPC_SET

Sets the message queue identifier by copying selected values in the structure specified by the buf parameter into corresponding fields in the msqid_ds structure associated with the message queue identifier.

This is a restricted operation. The effective user ID of the calling process must have appropriate privileges or must be equal to the value of the owner’s user ID (msg_perm.uid field) or the creator’s user ID (msg_perm.cuid field) in the associated

msqid_ds structure.

Only a process with appropriate privileges can increase the value of msg_qbytes.

IPC_SETNONFT

Disables fault tolerance for the message queue specified by the

msqid parameter. The default operation of message queues makes them fault tolerant so that interprocess communication does not lose data.

This is a restricted operation. The effective user ID of the calling process must have appropriate privileges or must be equal to the value of the owner’s user ID (msg_perm.uid field) or the creator’s user ID (msg_perm.cuid field) in the associated

msqid_ds structure.

527186-003 Hewlett-Packard Company 4

33

msgctl(2) OSS System Calls Reference Manual

buf

IPC_STAT

Queries the message queue identifier by copying the contents of its associated msqid_ds data structure into the structure specified by the buf parameter.

Specifies the address of a msqid_ds structure. This structure is used only with the IPC_STAT and IPC_SET values of the cmd parameter. With IPC_STAT, the results of the query are copied to this structure. With IPC_SET, the values in this structure are used to set certain fields in the msqid_ds structure associated with the message queue identifier. In either case, the calling process must have allocated the structure before making the call.

DESCRIPTION

The msgctl( ) function allows a process to query or set the contents of the msqid_ds structure associated with the specified message queue identifier. It also allows a process to remove the message queue identifier and its associated msqid_ds structure. The value of the cmd parameter determines which operation is performed.

The IPC_SET value of the cmd parameter uses the user-supplied contents of the buf parameter to set the corresponding fields of the msqid_ds structure associated with the message queue identifier:

The owner’s user ID field (msg_perm.uid) is set as specified in the input.

The owner’s group ID field (msg_perm.gid) is set as specified in the input.

The access modes field (msg_perm.mode) is set as specified in the low-order nine bits of the corresponding field in the input.

The maximum number of bytes field (msg_qbytes) for the queue is set as specified in the input.

The field for the time of the last msgctl( ) operation that changed the structure

(msg_ctime) is set as specified in the input.

Message Queue Use Between Environments

Guardian processes cannot use OSS functions for access to OSS message queues. If called from a Guardian process, this function fails and errno is set to [ENOTOSS].

RETURN VALUES

Upon successful completion, the value 0 (zero) is returned. Otherwise, the value -1 is returned, and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the msgctl( ) function sets errno to the value that corresponds to the condition.

[EACCES]

[EFAULT]

[EINVAL]

The cmd parameter is IPC_STAT, but the calling process does not have read permission.

The msqid_ds structure associated with the message queue identifier cannot be found.

One of the following conditions exists:

The msqid parameter does not specify a valid message queue identifier.

The cmd parameter is not a valid command.

4

34 Hewlett-Packard Company 527186-003

System Functions (k - m) msgctl(2)

All processes for the relevant message server have failed.

The message queue corresponding to the value specified as the msqid parameter has been removed from the system.

[EMSGQNOTRUNNING]

The message queue server associated with the message queue identifier is not running.

[ENOTOSS] The calling process is not an OSS process. The requested operation is not supported from the Guardian environment.

[EPERM] One of the following conditions exists:

The cmd parameter is equal to either IPC_RMID or IPC_SET, and the calling process does not have appropriate privileges.

The cmd parameter is equal to IPC_SET, and an attempt is being made to increase the value of the msg_qbytes field when the effective user ID of the calling process does not have appropriate privileges.

RELATED INFORMATION

Functions: msgget(2), msgrcv(2), msgsnd(2).

STANDARDS CONFORMANCE

The following are HP extensions to the XPG4 Version 2 specification:

The IPC_SETNONFT value for the cmd parameter is supported.

The errno values [EFAULT], [EMSGQNOTRUNNING], and [ENOTOSS] can be returned.

527186-003 Hewlett-Packard Company 4

35

msgget(2) OSS System Calls Reference Manual

NAME

msgget - Creates or returns the identifier for a message queue

LIBRARY

G-series native OSS processes: /G/system/sysnn/zossksrl

H-series OSS processes: /G/system/zdllnnn/zosskdll

SYNOPSIS

#include <sys/msg.h>

int msgget(

key_t key,

int msgflg);

PARAMETERS

key msgflg

Specifies the key that identifies the message queue. The IPC_PRIVATE key can be used to ensure the return of a new (unused) message queue identifier.

Specifies the following creation flag values:

IPC_CREAT

If the key does not exist, the msgget( ) function creates a message queue identifier using the given key.

IPC_CREAT | IPC_EXCL

If the key already exists, the msgget( ) function fails and returns an error notification.

DESCRIPTION

The msgget( ) function returns the message queue identifier for the message queue identified by the key parameter. If the key parameter already has a message queue identifier associated with it and (msgflg & IPC_CREAT) is 0 (zero), that identifier is returned.

A new message queue identifier and its associated data structure are created when either of the following is true:

The value of IPC_PRIVATE is used for the key parameter.

The key parameter does not already have a message queue identifier associated with it, and (msgflg & IPC_CREAT) is not 0 (zero).

After creating a new message queue identifier, the msgget( ) function initializes the msqid_ds structure associated with the identifier as follows:

The msg_perm.cuid and msg_perm.uid fields are set to the effective user ID of the calling process.

The msg_perm.cgid and msg_perm.gid fields are set to the effective group ID of the calling process.

The low-order nine bits of the msg_perm.mode field are set to the low-order nine bits of

msgflg.

The msg_qnum, msg_lspid, msg_lrpid, msg_stime, and msg_rtime fields are all set to

0 (zero).

4

36 Hewlett-Packard Company 527186-003

System Functions (k - m) msgget(2)

The msg_ctime field is set to the current time. This field is updated when any of the following events occur:

— The message queue identifier is created.

— The message queue identifier is removed.

The msg_qbytes field is set to the system limit.

The message queue identifier is used for the following purposes:

It identifies a specific message server.

It allows detection of references to a previously removed message queue.

It allows detection of attempts to reference message queues in other processors.

Key Creation

The key represents a user-designated name for a given message queue. Keys are usually selected by calling the ftok( ) function before calling the msgget( ) function. The ftok( ) function returns a key based on a path and an interprocess communications identifier. This key is passed to the

msgget( ) function, which returns a message queue identifier.

The message queue identifier is then used in calls to the msgctl( ), msgrcv( ), and msgsnd( ) functions.

Uniqueness of Identifiers

The system recycles no-longer-used message queue identifiers after a long time elapses.

Processor or Disk Process Failures

If a processor fails and if its OSS message-queue server was running as a process pair, no queued messages are lost. The backup server process takes over, and there are no effects on the successful completion of this function.

If the OSS message-queue server was not running as a process pair when its processor failed, queued messages are lost and the function call fails with errno set to [EINVAL]. Thereafter, a process cannot successfully call any function using the associated message queue identifier.

Cleaning Up Message Queue Identifiers

A message queue identifier remains allocated until it is removed. An allocated message queue identifier is not removed when the last process using it terminates. The user must remove allocated message queue identifiers that are not attached to processes to avoid wasting system resources.

The status of message queue identifiers can be checked with the ipcs command. Message queue identifiers can be removed using the ipcrm command. The associated data structure is removed only after the final detach operation.

Message Queue Use Between Environments

Guardian processes cannot use OSS functions for access to OSS message queues. Such a call fails, and errno is set to [ENOTOSS].

RETURN VALUES

Upon successful completion, a message queue identifier is returned. Otherwise, the value -1 is returned and errno is set to indicate the error.

527186-003 Hewlett-Packard Company 4

37

msgget(2) OSS System Calls Reference Manual

ERRORS

If any of the following conditions occurs, the msgget( ) function sets errno to the value that corresponds to the condition.

[EACCES]

[EEXIST]

[EFAULT]

[EINVAL]

A message queue identifier exists for the key parameter but operation permission, which is specified by the low-order nine bits of the msgflg parameter, is not granted.

A message queue identifier exists for the key parameter, and both IPC_CREAT and IPC_EXCL are set.

The msqid_ds structure associated with the message queue identifier cannot be found.

One of the following conditions exists:

All processes for the relevant message server have failed.

The message queue corresponding to the message queue identifier associated with the key parameter has been removed from the system.

[EMSGQNOTRUNNING]

The message queue server associated with the message queue identifier is not running.

[ENOENT] A message queue identifier does not exist for the key parameter and the

IPC_CREAT value is not set.

[ENOSPC] A message queue identifier cannot be created because the system-imposed limit on the maximum number of allowed message queue identifiers would be exceeded.

[ENOTOSS] The calling process is not an OSS process. The requested operation cannot be performed from the Guardian environment.

RELATED INFORMATION

Commands: ipcrm(1), ipcs(1).

Functions: ftok(3), msgctl(2), msgrcv(2), msgsnd(2).

STANDARDS CONFORMANCE

The following are HP extensions to the XPG4 Version 2 specification:

The errno values [EFAULT], [EINVAL], [EMSGQNOTRUNNING], and [ENOTOSS] can be returned.

4

38 Hewlett-Packard Company 527186-003

System Functions (k - m) msgrcv(2)

NAME

msgrcv - Receives a message from a message queue

LIBRARY

G-series native OSS processes: /G/system/sysnn/zossksrl

H-series OSS processes: /G/system/zdllnnn/zosskdll

SYNOPSIS

#include <sys/msg.h> int msgrcv(

int msqid,

void *msgp,

size_t msgsz,

long int msgtyp,

int msgflg);

PARAMETERS

msqid msgp msgsz msgtyp msgflg

Specifies the identifier of the message queue from which to read a message.

Specifies a pointer to the msgbuf structure that is to receive the message. (See the NOTES section.)

Specifies the maximum number of bytes allowed for the received message.

Specifies the message type to read from the queue.

Specifies the action to be taken by the system if there are no msgtyp messages in the queue. This parameter also specifies whether to truncate the message if its length exceeds the value specified by msgsz.

DESCRIPTION

The msgrcv( ) function reads a message from the queue associated with the msqid parameter. It returns the number of bytes in the received message.

The msgp parameter points to a user-defined msgbuf structure. The structure receives the message read from the queue.

The msgsz parameter specifies the maximum size allowed for the received message. If the message is longer than the value specified by the msgsz parameter, the system takes one of the following actions:

If the MSG_NOERROR flag is used in the msgflg parameter, the system truncates the message to msgsz bytes and discards the truncated portion without notifying the calling process.

If the MSG_NOERROR flag is not used in the msgflg parameter, the system returns an

errno value of [E2BIG] to the calling process and leaves the message in the queue.

The msgtyp parameter specifies the message type that the process wants to receive. Possible values and their results are as follows:

0 (zero) The process receives the message at the head of the queue.

> 0 (positive) The process receives the first message of the requested message type.

527186-003 Hewlett-Packard Company 4

39

msgrcv(2) OSS System Calls Reference Manual

< 0 (negative) The process receives the first message of the lowest type on the queue. To qualify as the lowest type, a message’s type must be less than or equal to the absolute value of the msgtyp parameter.

The msgflg parameter specifies the action that the system should take if the queue does not contain a message of the requested type. Either of two system actions can be specified, as follows:

If the IPC_NOWAIT flag is used, the function call returns immediately with the value -1 and errno is set to [ENOMSG].

If the IPC_NOWAIT flag is not used, the system suspends the calling process. The process remains suspended until one of the following occurs:

— A message of the requested type appears in the queue. In this case, the system wakes the process to receive the message.

— The specified message queue identifier is removed from the system. In this case, the system sets errno to [EIDRM] and returns the value -1 to the calling process.

— The process catches a signal. In this case, the process does not receive the message; instead, it resumes execution as directed by a sigaction( ) function call.

Message Queue Use Between Environments

Guardian processes cannot use OSS functions to access OSS message queues. If called from a

Guardian process, the function call fails and errno is set to [ENOTOSS].

NOTES

The IPC_NOWAIT flag is defined in the sys/ipc.h header file.

The user-supplied msgbuf structure, used to store received messages, can be defined as follows:

struct msgbuf { long int mtype; char mtext[ ];

};

The mtype field is set to the message type assigned by the sender.

The mtext field is set to the message text. The message size is less than or equal to the value of the msgsz parameter specified in the last successful call to msgrcv( ).

RETURN VALUES

Upon successful completion, the msgrcv( ) function returns the number of bytes actually stored in the mtext field. Also, the system updates the msqid_ds structure associated with the message queue identifier as follows:

Decrements the value in the msg_qnum field by 1.

Decrements the value in the msg_cbytes field by the message text size.

Sets the msg_lrpid field to the OSS process ID of the calling process.

Sets the msg_rtime field to the current time.

When the msgrcv( ) function fails, the value -1 is returned and errno is set to indicate the error.

4

40 Hewlett-Packard Company 527186-003

System Functions (k - m) msgrcv(2)

ERRORS

If any of the following conditions occurs, the msgrcv( ) function sets errno to the value that corresponds to the condition.

[E2BIG]

[EACCES]

[EFAULT]

[EIDRM]

[EINTR]

[EINVAL]

The number of bytes to be received in the mtext field is greater than the value of the msgsz parameter and the MSG_NOERROR flag is used in the msgflg parameter.

The calling process does not have read permission for the specified message queue.

The msqid_ds structure associated with the message queue identifier cannot be found.

The message queue identified by the msqid parameter has been removed from the system.

The operation was interrupted by a signal.

One of the following conditions exists:

The msqid parameter does not specify a valid message queue identifier.

The value of the msgsz parameter is less than 0 (zero).

All processes for the relevant message server have failed.

[EMSGQNOTRUNNING]

The message queue server associated with the message queue identifier is not running.

[ENOMSG] The queue does not contain a message of the requested type and the

IPC_NOWAIT flag is used in the msgflg parameter.

[ENOTOSS] The calling process is not an OSS process. The requested operation cannot be performed from the Guardian environment.

RELATED INFORMATION

Functions: msgctl(2), msgget(2), msgsnd(2), sigaction(2).

STANDARDS CONFORMANCE

The following are HP extensions to the XPG4 Version 2 specification:

The errno values [EFAULT], [EMSGQNOTRUNNING], and [ENOTOSS] can be returned.

527186-003 Hewlett-Packard Company 4

41

msgsnd(2) OSS System Calls Reference Manual

NAME

msgsnd - Sends a message to a message queue

LIBRARY

G-series native OSS processes: /G/system/sysnn/zossksrl

H-series OSS processes: /G/system/zdllnnn/zosskdll

SYNOPSIS

#include <sys/msg.h> int msgsnd(

int msqid,

const void *msgp,

size_t msgsz,

int msgflg);

PARAMETERS

msqid msgp msgsz msgflg

Specifies the identifier of the message queue in which to place the message. The identifier is typically returned by a previous call to the msgget( ) function.

Specifies a pointer to the msgbuf structure that contains the message. (See the

NOTES section.)

Specifies the size of the data array in the msgbuf structure.

Specifies the action to be taken by the system if it runs out of internal buffer space.

DESCRIPTION

The msgsnd( ) function sends a message to the queue associated with the msqid parameter.

The msgp parameter points to a user-defined msgbuf structure. The structure identifies the message type and contains a data array with the message text.

The size of the data array is specified by the msgsz parameter. The msgsz value can be from 0

(zero) through a system-defined maximum.

The msgflg parameter specifies the action that the system should take if either or both of the following are true:

The current number of bytes in the message queue is equal to msg_qbytes (in the

msqid_ds structure).

The total number of messages in all message queues is equal to the system-defined limit.

Either of two system actions can be specified, as follows:

If the IPC_NOWAIT flag is used in the msgflg parameter, the system does not send the message and returns to the calling process immediately.

If the IPC_NOWAIT flag is not used in the msgflg parameter, the system suspends the calling process. The process remains suspended until one of the following occurs:

— The blocking condition is removed. In this case, the system sends the message.

— The specified message queue identifier is removed from the system. In this case, the system sets errno to [EIDRM] and returns the value -1 to the calling process.

4

42 Hewlett-Packard Company 527186-003

System Functions (k - m) msgsnd(2)

— The process catches a signal. In this case, the message is not sent and the process resumes execution as directed by a sigaction( ) function call.

If the msgsnd( ) function finishes successfully, the system updates the msqid_ds structure associated with the msqid parameter. Specifically, it does the following:

Increments the value in the msg_qnum field by 1.

Increments the value in the msg_cbytes field by the message text size.

Sets the msg_lspid field to the OSS process ID of the calling process.

Sets the msg_stime field to the current time.

Message Queue Use Between Environments

Guardian processes cannot use OSS functions to access OSS message queues. If called from a

Guardian process, the function call fails and errno is set to [ENOTOSS].

NOTES

The IPC_NOWAIT flag is defined in the sys/ipc.h header file.

The user-supplied msgbuf structure can be defined as follows:

struct msgbuf { long int mtype; char mtext[ ];

};

The mtype field is a user-chosen positive integer that represents the message type. A receiving process can use the message type to select only those messages it wants to receive from the queue. (See the msgrcv(2) reference page.)

The mtext field contains any text of the length specified by the msgsz parameter.

RETURN VALUES

Upon successful completion, the value 0 (zero) is returned. Otherwise, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the msgsnd( ) function sets errno to the value that corresponds to the condition.

[EACCES]

[EAGAIN]

[EFAULT]

[EIDRM]

[EINTR]

The calling process does not have the correct access permission for the operation.

The IPC_NOWAIT flag is used in the msgflg parameter, and either the maximum number of message headers has been allocated or the size of the message exceeds the amount of space currently available on the target queue.

The msqid_ds structure associated with the message queue identifier cannot be found.

The message queue identified by the msqid parameter has been removed from the system.

The operation was interrupted by a signal.

527186-003 Hewlett-Packard Company 4

43

msgsnd(2) OSS System Calls Reference Manual

[EINVAL] One of the following conditions is true:

The msqid parameter does not specify a valid message queue identifier.

The value of the mtype field is less than 1.

The value of the msgsz parameter is less than 0 (zero) or greater than the system-defined limit.

All processes for the relevant message server have failed.

[EMSGQNOTRUNNING]

The message queue server associated with the message queue identifier is not running.

[ENOTOSS] The calling process is not an OSS process. The requested operation cannot be performed from the Guardian environment.

RELATED INFORMATION

Functions: msgctl(2), msgget(2), msgrcv(2), sigaction(2).

STANDARDS CONFORMANCE

The following are HP extensions to the XPG4 Version 2 specification:

The errno values [EFAULT], [EMSGQNOTRUNNING], and [ENOTOSS] can be returned.

4

44 Hewlett-Packard Company 527186-003

Section 5. System Functions (n - p)

This section contains reference pages for Open System Services (OSS) system function calls with names that begin with n through p. These reference pages reside in the cat2 directory and are sorted alphabetically by U.S. English conventions in this section.

527186-003 Hewlett-Packard Company 5

1

nice(2) OSS System Calls Reference Manual

NAME

nice - Changes the scheduling priority of the calling process

LIBRARY

G-series native Guardian processes: system library

G-series native OSS processes: system library

H-series native Guardian processes: implicit libraries

H-series OSS processes: implicit libraries

SYNOPSIS

#include <unistd.h> int nice(

int increment);

PARAMETERS

increment

Specifies a value that is added to the current nice value of the calling process.

The nice value of the calling process is maintained by the system and affects the scheduling priority of the process. Increasing the nice value lowers the scheduling priority of the process. Decreasing the nice value increases the scheduling priority of the process.

If the value specified for increment increases the nice value of the calling process such that it exceeds the maximum value possible for nice, nice is set to its maximum value.

A negative value can be specified for increment if the process has appropriate privileges.

If the value specified for increment decreases the nice value of the calling process such that it becomes less than the minimum value possible for nice, nice is set to its minimum value.

DESCRIPTION

The nice( ) function increases or decreases the nice value of the calling process.

The nice value is a nonnegative number in the range 0 through (2*NZERO -1). NZERO is defined in the limits.h header file.

The nice value is a relative value for scheduling priority among executing processes. The nice value of a parent process is passed to a child process during a call to the fork( ), tdm_fork( ),

tdm_spawn( ), and tdm_spawnp( ) functions. The nice value of a calling process is passed to a new process image during a call to any of the exec or tdm_exec sets of functions.

The nice value is an attribute of a process in both the Guardian and OSS environments. The default value of nice for a newly created process is the value defined for NZERO in the limits.h header file. The nice value affects scheduling priority but does not determine scheduling priority.

Use on Guardian Objects

The nice( ) function can only be used by a process on itself.

The Guardian priority of a process after a call to the nice( ) function is calculated as follows:

New Guardian priority = old Guardian priority

- (new nice value - old nice value) which is the same as:

New Guardian priority = old Guardian priority

- ((old nice value + increment) - old nice value)

5

2 Hewlett-Packard Company 527186-003

System Functions (n - p) nice(2)

If the sum of the old nice value and the increment is

• less than 0 (zero), then the new nice value is 0 (zero).

• greater than 39, then the new nice value is 39 because the current value of 2*NZERO -1 is 39.

Refer to NOTES for a description of the relative priorities of Guardian and OSS processes.

Use From the Guardian Environment

The nice( ) function can be used from the Guardian environment.

NOTES

Changing the Guardian priority of a process does not affect the nice value of the process.

The nice value of a process can also be changed by a call to the Guardian procedure

PROCESS_SETINFO_. The nice value can be determined by a call to the Guardian procedure

PROCESS_GETINFOLIST_. Refer to the Guardian Procedure Calls Reference Manual for additional information.

The nice value is not the value used by the operating system to compare scheduling priorities among processes in all environments.

The scheduling priority for processes running in the Guardian environment is defined as increasing as the priority number increases. This convention is the opposite of the convention used on

UNIX systems, where a lower priority number means a higher scheduling priority.

Processes running in the OSS environment have their scheduling priorities determined using

UNIX conventions. The OSS priority of a process after a call to the nice( ) function is calculated as follows:

New OSS priority = 199 - new Guardian priority

- new nice value which is the same as:

New OSS priority = 199 - new Guardian priority

- (old nice value + increment)

RETURN VALUES

Upon successful completion, the nice( ) function returns the new nice value minus the value of

NZERO. If the function call fails, the value -1 is returned, the nice value for the process is not changed, and errno is set to indicate the error.

Because a value of -1 also can be returned by a successful completion of the function call, an application program that needs to check for failure of the function call should set errno to 0

(zero) before calling the nice( ) function.

ERRORS

If the following condition occurs, nice( ) sets errno to the corresponding value:

[EPERM] The calling process specified a negative value for the increment parameter but does not have appropriate privileges.

RELATED INFORMATION

Functions: execl(2), execle(2), execlp(2), execv(2), execve(2), execvp(2), fork(2),

tdm_execve(2), tdm_execvep(2), tdm_fork(2), tdm_spawn(2), tdm_spawnp(2).

527186-003 Hewlett-Packard Company 5

3

open(2) OSS System Calls Reference Manual

NAME

open - Opens a file for reading or writing, creates a regular file in the OSS environment

LIBRARY

G-series native Guardian processes: system library

G-series native OSS processes: system library

H-series native Guardian processes: implicit libraries

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/types.h>

/* optional except for POSIX.1 */

#include <sys/stat.h>

#include <fcntl.h>

/* optional except for POSIX.1 */

int open(

const char *path,

int oflag

[ , mode_t mode ]);

PARAMETERS

path oflag mode

Points to the pathname of the file to be opened or created.

The files /lost+found, /dev, /dev/tty, and /dev/null cannot be specified for this parameter when the O_CREAT flag is set for the oflag parameter. Attempts to create these files cause the function call to fail and errno to be set to [EINVAL].

If the path parameter refers to a symbolic link, the open( ) function opens the file pointed to by the symbolic link.

If the path parameter refers to a file in the Guardian file system (/G), additional restrictions apply. See the subsection Opening Guardian Files in the

DESCRIPTION section of this reference page for more information.

Specifies the type of access, special open processing, the type of update, and the initial state of the open file. The parameter value is constructed by logically

ORing special open processing flags. These flags are defined in the fcntl.h header file and are described in DESCRIPTION.

Specifies the read, write, and execute permissions of the file and the file type flags for the file.

This parameter is required if the file does not exist and the O_CREAT flag is set in the oflag parameter. If the file already exists but O_CREAT is set, this parameter must be specified and must have a valid value but has no effect.

If this parameter is specified when values other than O_CREAT are used in the

oflag parameter, the values specified for mode have no effect on whether the file is opened for reading or writing.

The permission bits are set according to the value of this parameter modified by the process’s file creation mask (see the umask(2) reference page). The value of this parameter is constructed by logically ORing flags that are defined in the

sys/stat.h header file.

The file type flags are described in DESCRIPTION.

5

4 Hewlett-Packard Company 527186-003

System Functions (n - p) open(2)

DESCRIPTION

The open( ) function establishes a connection between the file indicated by the path parameter and the returned file descriptor. The opened file descriptor is used by subsequent I/O functions, such as read( ) and write( ), to access that file.

The returned file descriptor is the lowest-numbered file descriptor not previously open for that process. A corresponding Guardian environment file number is also assigned.

The file offset, marking the current position within the file, is set to the beginning of the file. The new file descriptor is set to remain open across the processing of any of the exec or tdm_exec set of functions. (See the fcntl(2) reference page.)

The file status flags and file access flags are designated by the oflag parameter. The oflag parameter is constructed by a bitwise-inclusive-OR of exactly one of the file access flags (O_RDONLY,

O_WRONLY, or O_RDWR) with one or more of the file status flags.

The open( ) function cannot be used to create a FIFO special file. Use the mkfifo( ) function for that purpose.

File Access Flags

The file access flags are:

O_RDONLY

The file is open only for reading.

O_WRONLY The file is open only for writing.

O_RDWR

The file is open for reading and writing.

Exactly one of the file access flags must be specified.

File Status Flags

The file status flags that specify special open processing are:

O_CREAT

Create and open the file. If the file exists, this flag has no effect except as noted under the O_EXCL flag. If the file does not exist, a regular file is created with these characteristics:

The owner ID of the file is set to the effective user ID of the process.

The group ID of the file is determined by the value of the S_ISGID flag in the parent directory. If S_ISGID is set, the group ID of the file is set to the group ID of the parent directory; otherwise, the group ID of the file is set to the effective group ID of the calling process. If the file is a Guardian file (that is, within /G), the group ID is set to that of the primary group of the effective user ID.

The file permission and attribute bits are set to the value of the mode parameter, modified as listed:

— All bits set in the process file mode creation mask are cleared.

— The set user ID attribute (S_ISUID bit) is cleared.

— The set group ID attribute (S_ISGID bit) is cleared.

If bits other than the file permission and appropriate file-type bits are set in the mode parameter, errno is set to [EINVAL].

527186-003 Hewlett-Packard Company 5

5

open(2) OSS System Calls Reference Manual

O_EXCL

Open the file in exclusive access mode.

If the file exists and the O_EXCL and O_CREAT flags are set, the open fails. If the file exists and the O_EXCL flag is set and the O_CREAT flag is not set, the open succeeds.

O_NOCTTY

Open the file but not as a controlling terminal. If the path parameter identifies a terminal device, this flag ensures that the terminal device does not become the controlling terminal for the process.

When opening a file that is not a terminal device, the O_NOCTTY flag is ignored.

O_TRUNC

Open the file and empty it. If the file does not exist or if the file is not a regular file, this flag has no effect. If the file exists and is a regular file, and if the file is successfully opened with either read/write access or write-only access, then:

The length of the file is truncated to 0 (zero).

The owner and group of the file are unchanged.

The set user ID attribute of the file mode is cleared.

The open fails if any of these conditions are true:

The file supports enforced record locks, and another process has locked a portion of the file.

The file does not allow write access.

The oflag parameter also specifies the O_RDONLY flag.

If the oflag parameter also specifies the O_SYNC flag, the truncation is a synchronous update.

A program can request some control over when updates should be made permanent for a regular file opened for write access.

The file status flags that define the initial state of the open file are:

O_APPEND

Open the file only for append access. If set, the file pointer is set to the end of the file before each write.

This flag is ignored for Telserv terminal devices.

O_NONBLOCK

Open the file for nonblocked access. If set, the call to open( ) does not block, and subsequent read( ) or write( ) operations on the file are nonblocking.

When opening a regular disk file or an OSS directory, the O_NONBLOCK flag is ignored.

Calling the open( ) function with the O_NONBLOCK flag for FIFO files and for character special devices that support nonblocking opens is supported.

Calling the open( ) function with the O_NONBLOCK flag is supported for Telserv terminal devices (tty) as listed:

For a static window, the open operation is always allowed; it finishes when the connection is established.

5

6 Hewlett-Packard Company 527186-003

System Functions (n - p) open(2)

O_SYNC

For a dynamic window, the open operation is allowed only if a connection is already established.

Calling the open( ) function with the O_NONBLOCK flag is supported for

OSSTTY terminal devices (ztty). OSSTTY devices support only three static windows, one each for #stdin, #stdout, and #stderr.

Open for synchronized update. If set, updates and writes to regular files are synchronous updates. This flag is ignored for files that are not regular files. File update is performed by:

The open( ) function with the O_TRUNC flag

The write( ) function

On return from a call to either of these functions that performs a synchronous update (a call with the O_SYNC flag set), the calling process is ensured that all data for the file has been written to permanent storage, even if the file is also open for deferred update. OSS file-system data caching is disabled for write operations on files for which this flag is set.

Synchronous updates provide the highest level of data integrity protection but the slowest performance. Compare with the use of the S_NONSTOP flag, as described in File Type Flags later in this reference page.

General Notes on oflag Parameter Flag Values

The effect of setting the O_CREAT flag is immediate.

When opening a file with the O_CREAT flag set:

If the named file does not already exist, a regular disk file is created.

If the named file is not a regular file, the O_CREAT flag is ignored.

When opening a FIFO file with the O_RDONLY flag set:

If the O_NONBLOCK flag is not set, the open( ) function blocks until another process opens the file for writing. If the file is already open for writing (even by the calling process), the function returns without delay.

If the O_NONBLOCK flag is set, the open( ) function returns immediately.

When opening a FIFO file with the O_WRONLY flag set:

If the O_NONBLOCK flag is not set, the open( ) function blocks until another process opens the file for reading. If the file is already open for reading (even by the calling process), the function returns without delay.

If the O_NONBLOCK flag is set, the open( ) function returns an error if no process currently has the file open for reading.

The O_RDWR file access flag is supported when opening a FIFO file; the call to the open( ) function finishes immediately, even if the O_NONBLOCK flag is not set.

When opening a character special file that supports nonblocking opens, such as a terminal device:

If the O_NONBLOCK flag is not set, the open( ) function blocks until the device is ready or available.

527186-003 Hewlett-Packard Company 5

7

open(2) OSS System Calls Reference Manual

If the O_NONBLOCK flag is set, the open( ) function returns without waiting for the device to be ready or available. Subsequent behavior of the device is device-specific.

When opening a directory, the open fails, and errno is set to [EISDIR], if either of these conditions is true:

The directory is /E or /G (the Guardian file system) or a directory within /G.

The directory is not /E or /G and is not within /E or /G, and the file access flag is either

O_WRONLY or O_RDWR.

File Type Flags

The file type flags that can be logically ORed into the value specified in the mode parameter are:

S_IFREG

Regular file in the OSS file system or in /G, the Guardian file system.

S_ISVTX

Sticky bit; used only for directories (cannot be used for files in /G, the Guardian file system).

S_NONSTOP Regular file in the OSS file system protected by disk process checkpointing.

(Files in /G cannot have this flag set.)

When set, this flag indicates that return from a write operation does not occur until both the primary and backup disk processes have the data (thereby protecting the data against a single point of failure).

OSS file-system data caching is disabled for write operations on files for which this flag is set. Performance is slower than when caching is used, but data integrity protection increases. Performance is faster than when the O_SYNC flag in the oflag parameter is used, but data integrity protection is less than that provided by O_SYNC use.

Opening Guardian Files

If the file is a Guardian file (that is, if it is in the /G file system):

The file can be opened only if it is:

— A format 1 file on a physical disk volume and one of the following:

— An odd, unstructured Enscribe file. In this case, it is opened as a regular file with a primary and secondary extent size that is a multiple of 2. If the extent size is odd, the open fails.

If the unstructured buffer size was not 4096, a successful open makes the buffer size 4096 (as if the Guardian procedure SETMODE was called for mode 93 with a parameter value of 4096).

— An EDIT file (file code 101). In this case, it is opened as a regular file for read-only access.

— A TTY simulation process.

An attempt to open:

— A format 2 file

5

8 Hewlett-Packard Company 527186-003

System Functions (n - p) open(2)

— A structured file

— A file administered through the Storage Management Foundation (SMF)

— Any file or device of any other type not described here fails with errno set, usually to [EINVAL]. An attempt to open a volume, a subvolume, or a process other than a TTY simulation process (/G/vol, /G/vol/subvol, or /G/process, respectively) fails with errno set to [EISDIR].

An attempt to open a subvolume with a reserved name beginning with ZYQ (for example, /G/vol2/zyq00004) fails with errno set to [EACCES].

An attempt to open a file within a subvolume with a reserved name beginning with ZYQ

(for example, /G/vol2/zyq00004/z000002x) fails with errno set to [EACCES].

If the file is not an EDIT file (that is, the file code is not 101), it is opened in shared exclusion mode.

If the file is an EDIT file and read-only access is specified, the file is opened in protected exclusion mode in the Guardian environment.

If the file is an EDIT file and write access is specified, the call fails with errno set to

[EINVAL].

The maximum number of opens is reported by the sysconf( ) function as the upper limit of opens per process. The actual limit depends on other factors, such as the size of the process file segment (PFS) and the number of existing opens on directories or on files in the Guardian environment.

If the open requires file creation, odd unstructured and file code 180 attributes are assumed.

If the open requires file creation, the file is given access permissions of rwxr-xr-x.

During open( ) processing, all access permissions are checked. This includes Guardian environment checks by Guardian standard security mechanisms (and by the Safeguard product) for

Guardian disk file and process access.

Use From the Guardian Environment

A call to the open( ) function in the Guardian environment requires an OSS pathname and returns an OSS file-system file descriptor, regardless of the file system containing the file.

The open( ) function belongs to a set of functions that have these effects when the first of them is called from the Guardian environment:

Two Guardian file-system file numbers (not necessarily the next two available) are allocated for the root directory and the current working directory. These file numbers cannot be closed by calling the Guardian FILE_CLOSE_ procedure.

The current working directory is assigned from the VOLUME attribute of the Guardian environment =_DEFAULTS DEFINE.

The use of static memory by the process increases slightly.

These effects occur only when the first of the set of functions is called. The effects are not cumulative.

527186-003 Hewlett-Packard Company 5

9

open(2) OSS System Calls Reference Manual

RETURN VALUES

Upon successful completion, the function returns the file descriptor, a nonnegative integer. Otherwise, the value -1 is returned, and errno is set to indicate the error.

ERRORS

If any of these conditions occurs, the function sets errno to the corresponding value:

[EACCES] One of these conditions exists:

Search permission is denied on a component of the pathname prefix.

The type of access specified by the oflag parameter is denied for the named file.

The file does not exist, and write permission is denied for the parent directory.

The O_TRUNC flag is specified, and write permission is denied.

The process attempted to open a Guardian subvolume with a reserved name beginning with ZYQ or a file within such a subvolume.

The process attempted to open a static Telserv window that is not yet connected.

[EEXIST] The O_CREAT and O_EXCL flags are set, and the named file exists.

[EFAULT] The path parameter is an invalid address.

[EFILEBAD] One of these conditions exists:

The function call attempted to open a Guardian EDIT file, but the structure of the file is bad.

The function call attempted to open a Guardian EDIT file, but the corrupted flag is set in the file label.

[EFSBAD] The fileset catalog for one of the filesets involved in the operation is corrupt.

[EGUARDIANOPEN]

The function call attempted to open a Guardian EDIT file for write access or for

Guardian shared or exclusive exclusion access, but the file has already been opened with a Guardian procedure call.

[EINTR]

[EINVAL]

A signal was caught during the open operation. This value is returned only for character special files (terminal devices) and for FIFO special files.

One of these conditions exists:

The call attempted to create a directory named lost+found in the root directory of an OSS fileset, or it attempted to create a directory named

/dev, /dev/tty, or /dev/null in the root directory of the OSS file system.

The function call specified the O_CREAT flag but did not specify the

mode parameter.

5

10 Hewlett-Packard Company 527186-003

System Functions (n - p) open(2)

[EIO]

[EISDIR]

The O_CREAT flag is set and bits other than the file permission and appropriate file type flags are set in the mode parameter.

Both the O_TRUNC flag and O_RDONLY flag are set.

None of the access flags O_RDONLY, O_WRONLY, or O_RDWR are set.

The function call attempted to create a Guardian file (that is, a file in the

/G file system), but the pathname cannot be mapped to a valid Guardian filename.

The function call attempted to open a Guardian file of a type other than those permitted.

The function call attempted to create a Guardian temporary file.

A physical input or output error occurred. The device where the file is stored might be in the down state, or both processors that provide access to the device might have failed.

Data might have been lost during transfer.

One of these conditions exists:

The named file is an OSS directory, and write access is requested.

The named file is a Guardian directory (/G or a directory in the /G file system).

[ELOOP] Too many symbolic links were encountered in translating the path parameter.

[EMFILE] The system limit for open file descriptors per process has reached the maximum permitted.

[ENAMETOOLONG]

One of these is too long:

The pathname pointed to by the path parameter

A component of the pathname pointed to by the path parameter

The intermediate result of pathname resolution when a symbolic link is part of the path parameter

The pathconf( ) function can be called to obtain the applicable limits.

[ENFILE] The maximum allowable number of files are currently open in this node.

[ENETDOWN]

The call was blocked during access to a FIFO, and communication has been lost with the remote node containing the other end of the FIFO.

[ENOENT] One of these conditions exists:

The O_CREAT flag is not set, and the named file does not exist.

527186-003 Hewlett-Packard Company 5

11

open(2) OSS System Calls Reference Manual

O_CREAT is set, and the pathname prefix does not exist.

The path parameter points to an empty string.

The function call attempted to open a file in the Guardian file system, but the specified pathname cannot be mapped to a valid Guardian filename.

The path parameter points to a file on a remote HP NonStop node, but communication with the remote node has been lost.

[ENOMEM] The system has insufficient resources to allow another open file.

[ENOROOT] One of these conditions exists:

The root fileset of the local node (fileset 0) is not in the STARTED state.

The current root fileset for the specified file is unavailable. The OSS name server for the fileset might have failed.

The specified file is on a remote HP NonStop node, and communication with the remote name server has been lost.

[ENOSPC] The directory that would contain the new file cannot be extended, the file does not exist, and the O_CREAT flag is set.

[ENOTDIR] A component of the pathname prefix is not a directory.

[ENXIO] One of these conditions exists:

The named file is a character special file, and the device associated with this special file does not exist.

The O_NONBLOCK flag is set, the named file is a FIFO file, the

O_WRONLY flag is set, and no process has the file open for reading.

The fileset containing the client’s current working directory or root directory is not mounted.

[EOPNOTSUPP]

The named file is a socket bound to the file system (not an AF_INET or

AF_INET6 socket) and cannot be opened.

[EOSSNOTRUNNING]

A required system process is not running.

[EPERM] One of these conditions exists:

The function call attempted to create a file named lost+found in the root directory of an OSS fileset.

The call attempted to create a file in /E.

[EROFS] The named file resides on a read-only fileset, and write access is required.

[ETXTBSY] The file is being executed, and the oflag value is O_WRONLY or O_RDWR.

For all other error conditions, errno is set to the appropriate Guardian file-system error number.

See the Guardian Procedure Errors and Messages Manual for more information about a specific

Guardian file-system error.

5

12 Hewlett-Packard Company 527186-003

System Functions (n - p) open(2)

RELATED INFORMATION

Functions: chmod(2), close(2), creat(2), fcntl(2), lseek(2), mknod(2), read(2), stat(2),

umask(2), write(2).

STANDARDS CONFORMANCE

The POSIX standards leave some features to the implementing vendor to define. These features are affected in the HP implementation:

The O_RDWR flag is supported for FIFO files.

The group ID of the new file is determined by the value of the O_ISGID flag in the parent directory.

The O_NONBLOCK flag is ignored for regular disk files and directory files.

The O_NOCTTY flag is ignored for regular disk files and directory files.

The O_CREAT flag is ignored for FIFOs and tty files.

If the O_CREAT flag is specified and bits other than the file permission and appropriate file type flags are set in the mode parameter, errno is set to [EINVAL].

If the O_TRUNC flag is specified and the O_RDONLY access flag is specified, the open fails.

The O_TRUNC flag is ignored for files other than regular files.

Attempting to open an OSS directory with an access flag of O_WRONLY or O_RDWR fails.

Specifying the O_NONBLOCK flag when opening character special devices that support nonblocking opens is supported.

HP extensions to the XPG4 Version 2 specification are:

Opening Guardian files (that is, files in the /G file system) is supported, as described under Opening Guardian Files in DESCRIPTION.

The errno values [EFAULT], [EFILEBAD], [EFSBAD], [EGUARDIANOPEN], [EIO],

[ELOOP], [ENETDOWN], [EOSSNOTRUNNING], and [EPERM] can be returned.

The file type S_NONSTOP is supported.

527186-003 Hewlett-Packard Company 5

13

pipe(2) OSS System Calls Reference Manual

NAME

pipe - Creates an interprocess communication channel

LIBRARY

G-series native Guardian processes: system library

G-series native OSS processes: system library

H-series native Guardian processes: implicit libraries

H-series OSS processes: implicit libraries

SYNOPSIS

#include <unistd.h> int pipe(

int filedes [2]);

PARAMETERS

filedes

Specifies the address of an array of two integers into which new file descriptors are placed.

DESCRIPTION

The pipe( ) function creates an interprocess channel called a pipe and returns two file descriptors in the parameters filedes[0] and filedes[1]. The file descriptor filedes[0] is opened for reading, and the file descriptor filedes[1] is opened for writing. Their integer values are the two lowest available at the time of the call to the pipe( ) function. The O_NONBLOCK flag is cleared on both file descriptors. (The fcntl( ) function can be used to set the O_NONBLOCK flag.)

Upon successful completion, the pipe( ) function marks the st_atime, st_ctime, and st_mtime fields of the pipe for update.

The FD_CLOEXEC flag is cleared on both file descriptors.

Use From the Guardian Environment

The pipe( ) function is one of a set of functions that have these effects when the first of them is called from the Guardian environment:

Two Guardian file system file numbers (not necessarily the next two available) are allocated for the root directory and the current working directory. These file numbers cannot be closed by calling the Guardian FILE_CLOSE_ procedure.

The current working directory is assigned from the VOLUME attribute of the Guardian environment =_DEFAULTS DEFINE.

The use of static memory by the process increases slightly.

These effects occur only when the first of the set of functions is called. The effects are not cumulative.

RETURN VALUES

Upon successful completion, the value 0 (zero) is returned. If the pipe( ) function fails, the value

-1 is returned, and errno is set to indicate the error.

ERRORS

If any of these conditions occurs, the pipe( ) function sets errno to the corresponding value:

[EFAULT] The filedes parameter is an invalid address.

5

14 Hewlett-Packard Company 527186-003

System Functions (n - p) pipe(2)

[EMFILE] No more file descriptors are available for this process.

[ENOMEM] The system has insufficient resources.

[ENOROOT] The function was called while the root fileset (fileset 0) was not available.

[EOSSNOTRUNNING]

The function was called while a required system process was not running.

For all other error conditions, errno is set to the appropriate Guardian file-system error number.

See the Guardian Procedure Errors and Messages Manual for more information about a specific

Guardian file-system error.

RELATED INFORMATION

Functions: fcntl(2), read(2), select(2), write(2).

Commands: sh(1).

STANDARDS CONFORMANCE

HP extensions to the XPG4 Version 2 specification are:

The errno values [EFAULT], [ENOROOT], and [EOSSNOTRUNNING] can be returned.

527186-003 Hewlett-Packard Company 5

15

pthread_atfork(2) OSS System Calls Reference Manual

NAME

pthread_atfork - Declares fork-handler routines to be called when the calling thread’s process forks a child process

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_atfork(

void ( *prepare ) ( void ),

void ( *parent ) ( void ),

void ( *child ) ( void ) );

PARAMETERS

prepare parent child

specifies the address of a routine that performs the fork preparation handling.

This routine is called in the parent process before the child process is created.

specifies the address of a routine that performs the fork parent handling. This routine is called in the parent process after the child process is created and before the return to the caller of fork( ).

specifies the address of a routine that performs the fork child handling. This routine is called in the child process before the return to the caller of fork( ).

DESCRIPTION

This function allows a main program or library to control resources during a fork( ) operation by declaring fork-handler routines, as follows:

The fork-handler routine specified by the prepare parameter is called before fork( ) executes.

The fork-handler routine specified by the parent parameter is called after fork( ) executes within the parent process.

The fork-handler routine specified by the child parameter is called in the new child process after fork( ) executes.

Your program (or library) can use fork handlers to ensure that program context in the child process is consistent and meaningful. After fork( ) executes, only the calling thread exists in the child process, and the state of all memory in the parent process is replicated in the child process, including the states of any mutexes, condition variables, and so on.

For example, in the new child process there might exist locked mutexes that are copies of mutexes that were locked in the parent process by threads that do not exist in the child process.

Therefore, any associated program state might be inconsistent in the child process.

The program can avoid this problem by calling pthread_atfork( ) to provide routines that acquire and release resources that are critical to the child process. For example, the prepare handler should lock all mutexes that you want to be usable in the child process. The parent handler just unlocks those mutexes. The child handler also unlocks them all — and might also create threads or reset any program state for the child process.

If no fork handling is desired, you can set any of this function’s parameters to NULL.

5

16 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_atfork(2)

EXAMPLES

If your library uses a mutex my_mutex, you might provide pthread_atfork( ) handler routines coded as follows:

void my_prepare(void)

{ pthread_mutex_lock(&my_mutex);

} void my_parent(void)

{ pthread_mutex_unlock(&my_mutex);

} void my_child(void)

{ pthread_mutex_unlock(&my_mutex);

/* Reinitialize state that doesn’t apply...like heap owned */

/* by other threads

}

*/

{

.

.

.

pthread_atfork(my_prepare, my_parent, my_child);

.

.

} fork();

NOTES

Do not call pthread_atfork( ) from within a fork-handler routine. Doing so could cause a deadlock.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0 Successful completion.

[ENOMEM] Insufficient table space exists to record the fork-handler routines’ addresses.

RELATED INFORMATION

Functions: pthread_create(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 5

17

pthread_attr_destroy(2) OSS System Calls Reference Manual

NAME

pthread_attr_destroy - Destroys a thread attributes object

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/ZDLLnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_attr_destroy(

pthread_attr_t *attr );

PARAMETERS

attr

specifies the thread attributes object to be destroyed.

DESCRIPTION

This function destroys a thread attributes object. Call this function when a thread attributes object will no longer be referenced.

Threads that were created using this thread attributes object are not affected by the destruction of this thread attributes object.

RETURN VALUES

This function always returns 0 (zero).

RELATED INFORMATION

Functions: pthread_attr_init(2), pthread_create(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

5

18 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_attr_getdetachstate(2)

NAME

pthread_attr_getdetachstate - Obtains the detachstate attribute of a thread attributes object

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_attr_getdetachstate(

const pthread_attr_t *attr,

int *detachstate );

PARAMETERS

attr detachstate

specifies the address of the thread attributes object whose detachstate attribute is obtained.

receives the value of the detachstate attribute.

DESCRIPTION

This function obtains the value of the detachstate attribute of the thread attributes object specified by the attr parameter and returns it in the detachstate parameter. This attribute specifies whether threads created using the specified thread attributes object are created in a detached state.

See the pthread_attr_setdetachstate(2) reference page either online or in the Open System Ser-

vices System Calls Reference Manual for information about the detachstate attribute.

RETURN VALUES

On successful completion, this function returns a zero and the detachstate attribute value is returned in detachstate. The attribute value PTHREAD_CREATE_JOINABLE indicates the thread is not detached, and the attribute value PTHREAD_CREATE_DETACHED indicates the thread is detached.

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0

[EINVAL]

Successful completion.

The attr parameter does not refer to an existing thread attributes object.

RELATED INFORMATION

Functions: pthread_attr_init(2), pthread_attr_setdetachstate(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 5

19

pthread_attr_getguardsize_np(2) OSS System Calls Reference Manual

NAME

pthread_attr_getguardsize_np - Obtains the guardsize attribute of a thread attributes object

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_attr_getguardsize_np(

const pthread_attr_t *attr,

size_t *guardsize );

PARAMETERS

attr

specifies the address of the thread attributes object whose guardsize attribute is obtained.

receives the value of the guardsize attribute.

guardsize

DESCRIPTION

This function obtains the value of the guardsize attribute of the thread attributes object specified by the attr parameter and returns it in the guardsize parameter. The specified thread attributes object must already be initialized when this function called.

When creating a thread, use a thread attributes object to specify nondefault values for thread attributes. The guardsize attribute of a thread attributes object specifies the minimum size (in bytes) of the guard area for the stack of a new thread.

A guard area can help a multithreaded program detect overflow of a thread’s stack. A guard area is a region of no-access memory that the system allocates at the overflow end of the thread’s stack. When any thread attempts to access a memory location within this region, a memory addressing violation occurs.

NOTES

The value of the guardsize attribute of a particular thread attributes object does not necessarily correspond to the actual size of the guard area of any existing thread in a multithreaded program.

Use of this function makes your application nonportable.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0

[EINVAL]

Successful completion.

The value specified by the attr parameter is invalid.

RELATED INFORMATION

Functions: pthread_attr_init(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification and to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

5

20 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_attr_getinheritsched(2)

NAME

pthread_attr_getinheritsched - Obtains the inherit scheduling attribute of a thread attributes object

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_attr_getinheritsched(

const pthread_attr_t *attr,

int *inheritsched );

PARAMETERS

attr

specifies the address of the thread attributes object whose inherit scheduling attribute is obtained.

inheritsched

receives the value of the inherit scheduling attribute.

DESCRIPTION

This function obtains the value of the inherit scheduling attribute of the thread attributes object specified by the attr parameter and returns it in the inheritsched parameter. The inherit scheduling attribute specifies whether threads created using the specified threads attributes object inherit the scheduling attributes of the creating thread or use the scheduling attributes stored in the threads attributes object specified by the pthread_create( ) attr parameter.

See the pthread_attr_setinheritsched(2) reference page either online or in the Open System

Services System Calls Reference Manual for information about the inherit scheduling attribute.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0

[EINVAL]

Successful completion.

The value specified by the attr parameter is invalid.

RELATED INFORMATION

Functions: pthread_attr_init(2), pthread_attr_setinheritsched(2), pthread_create(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 5

21

pthread_attr_getschedparam(2) OSS System Calls Reference Manual

NAME

pthread_attr_getschedparam - Obtains the scheduling parameters of the scheduling policy attribute of a thread attributes object

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_attr_getschedparam(

const pthread_attr_t *attr,

struct sched_param *param );

PARAMETERS

attr param

specifies the address of the thread attributes object with the scheduling policy attribute whose scheduling parameters are obtained.

receives the values of the scheduling parameters.

DESCRIPTION

This function obtains the values of the scheduling parameters of the scheduling policy attribute of the thread attributes object specified by the attr parameter and returns them in the param parameter.

See the pthread_attr_setschedparam(2) reference page either online or in the Open System Ser-

vices System Calls Reference Manual for information about the scheduling parameters.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0

[EINVAL]

Successful completion.

The value specified by the attr parameter is invalid.

RELATED INFORMATION

Functions: pthread_attr_init(2), pthread_attr_setschedparam(2), pthread_create(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

5

22 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_attr_getschedpolicy(2)

NAME

pthread_attr_getschedpolicy - Obtains the scheduling policy attribute of a thread attributes object

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_attr_getschedpolicy(

const pthread_attr_t *attr,

int *policy );

PARAMETERS

attr policy

specifies the address of the thread attributes object whose scheduling policy attribute is obtained.

receives the value of the scheduling policy attribute.

DESCRIPTION

This function obtains the value of the scheduling policy attribute of the thread attributes object specified by the attr parameter and returns it in the policy parameter. The scheduling policy attribute defines the scheduling policy for threads created using this threads attributes object.

See the pthread_attr_setschedpolicy(2) reference page either online or in the Open System Ser-

vices System Calls Reference Manual for information about the scheduling policy attribute.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0

[EINVAL]

Successful completion.

The value specified by the attr parameter is invalid.

RELATED INFORMATION

Functions: pthread_attr_init(2), pthread_attr_setschedpolicy(2), pthread_create(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 5

23

pthread_attr_getstackaddr(2) OSS System Calls Reference Manual

NAME

pthread_attr_getstackaddr - Obtains the stackbase address attribute of the specified thread attributes object

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_attr_getstackaddr(

const pthread_attr_t *attr,

void **stackaddr );

PARAMETERS

attr stackaddr

Specifies the address of the thread attributes object whose stack address attribute is obtained.

Receives the value of the stack address for the thread attributes object.

DESCRIPTION

This function obtains the value of the stackbase address attribute of the thread attributes object specified by the attr parameter and returns it in the stackaddr parameter. The specified attributes object must be initialized before this function is called.

RETURN VALUES

This function returns 0 (zero) upon successful completion of the call.

RELATED INFORMATION

Functions: pthread_attr_init(2), pthread_getattr_np(2), pthread_create(2).

STANDARDS CONFORMANCE

Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

5

24 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_attr_getstacksize(2)

NAME

pthread_attr_getstacksize - Obtains the stacksize attribute of a thread attributes object

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_attr_getstacksize(

const pthread_attr_t *attr,

size_t *stacksize );

PARAMETERS

attr stacksize

specifies the address of the thread attributes object whose stacksize attribute is obtained.

receives the value of the stacksize attribute.

DESCRIPTION

This function obtains the value of the stacksize attribute of the thread attributes object specified by the attr parameter and returns it in the stacksize parameter.

RETURN VALUES

On successful completion, this function returns a 0 (zero) and the stacksize attribute value is returned in stacksize.

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0

[EINVAL]

Successful completion.

The value specified by the attr parameter is invalid.

RELATED INFORMATION

Functions: pthread_attr_init(2), pthread_attr_setstacksize(2), pthread_create(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 5

25

pthread_attr_init(2) OSS System Calls Reference Manual

NAME

pthread_attr_init - Initializes a thread attributes object

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_attr_init(

pthread_attr_t *attr );

PARAMETERS

attr

specifies the address of the thread attributes object to be initialized.

DESCRIPTION

This function initializes the thread attributes object specified by the attr parameter with a set of default attribute values. A thread attributes object is used to specify the attributes of threads when they are created. A thread attributes object created by this function is used only in calls to the pthread_create( ) function.

The following functions change individual attributes of an initialized thread attributes object:

pthread_attr_setdetachstate( ) pthread_attr_setguardsize_np( ) pthread_attr_setinheritsched( ) pthread_attr_setschedparam( ) pthread_attr_setschedpolicy( ) pthread_attr_setstacksize( )

The attributes of a thread attributes object are initialized to default values. The default value of each attribute is discussed in the reference page for the corresponding function listed above.

When a thread attributes object is used to create a thread, the object’s attribute values determine the characteristics of the new thread. Thus, thread attributes objects act as additional arguments to thread creation. Changing the attributes of a thread attributes object does not affect any threads that were previously created using that thread attributes object.

You can use the same thread attributes object in successive calls to pthread_create( ), from any thread. (However, you cannot use the same value of the stack address attribute to create multiple threads that might run concurrently; threads cannot share a stack.) If more than one thread might change the attributes in a shared thread attributes object, your program must use a mutex to protect the integrity of the thread attributes object’s contents.

When you set the scheduling policy or scheduling parameters, or both, of a thread attributes object, scheduling inheritance must be disabled if you want the scheduling attributes you set to be used at thread creation. In the HP implementation, the default value of

PTHREAD_EXPLICIT_SCHED for the inherit attribute of a new thread automatically disables scheduling inheritance. At thread creation, the scheduling policy and scheduling parameters stored in the thread attributes object passed to the pthread_create( ) function are used by default. To enable scheduling inheritance, before creating the new thread use the

pthread_attr_setinheritsched( ) function to specify the value PTHREAD_INHERIT_SCHED for the inherit parameter.

5

26 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_attr_init(2)

RETURN VALUES

If an error condition occurs, the thread attributes object cannot be used and this function returns an integer value indicating the type of error. Possible return values are:

0

[EINVAL]

Successful completion.

The value specified by the attr parameter is not a valid thread attributes object.

[ENOMEM] Insufficient memory exists to initialize the thread attributes object.

RELATED INFORMATION

Functions: pthread_attr_destroy(2), pthread_attr_setdetachstate(2),

pthread_attr_setguardsize_np(2), pthread_attr_setinheritsched(2),

pthread_attr_setschedparam(2), pthread_attr_setschedpolicy(2),

pthread_attr_setstacksize(2), pthread_create(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 5

27

pthread_attr_setdetachstate(2) OSS System Calls Reference Manual

NAME

pthread_attr_setdetachstate - Sets the detachstate attribute of a thread attributes object

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_attr_setdetachstate(

pthread_attr_t *attr,

int detachstate );

PARAMETERS

attr detachstate

specifies the thread attributes object whose detachstate attribute is to be set.

specifies the new value for the detachstate attribute. Valid values are:

PTHREAD_CREATE_JOINABLE

This is the default value. Threads are created in "undetached" state.

PTHREAD_CREATE_DETACHED

A created thread is detached immediately, before it begins running.

DESCRIPTION

This function sets the value of the detachstate attribute of the thread attributes object specified by the attr parameter to the value specified by the detachstate parameter. The detachstate attribute specifies whether storage used by the thread can be reclaimed by the system when the thread terminates.

You cannot use the thread identifier (the value of type pthread_t that is returned by the

pthread_create( ) function) for a thread that is created detached in calls to the

pthread_detach( ) or pthread_join( ) functions.

When a thread that has not been detached finishes executing, the system retains the state of that thread to allow another thread to join with it. If the thread is detached before it finishes executing, the system can immediately reclaim the thread’s storage and resources when the thread terminates (that is, when it returns from its start routine, calls the pthread_exit( ) function, or is canceled.)

The pthread_join( ) or pthread_detach( ) function should eventually be called for every thread that is created with the detachstate attribute of its thread attributes object set to

PTHREAD_CREATE_JOINABLE, so that storage associated with the thread can be reclaimed.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0

[EINVAL]

Successful completion.

The value specified by the attr parameter is not a valid thread attributes object or the detachstate parameter is invalid.

5

28 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_attr_setdetachstate(2)

RELATED INFORMATION

Functions: pthread_attr_init(2), pthread_attr_getdetachstate(2), pthread_create(2),

pthread_join(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 5

29

pthread_attr_setguardsize_np(2) OSS System Calls Reference Manual

NAME

pthread_attr_setguardsize_np - Sets the guardsize attribute of a thread attributes object

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_attr_setguardsize_np(

pthread_attr_t *attr,

size_t guardsize );

PARAMETERS

attr guardsize

specifies the address of the thread attributes object whose guardsize attribute is to be set.

specifies the new value for the guardsize attribute.

DESCRIPTION

This function sets the value of the guardsize attribute of the thread attributes object specified by the attr parameter to the value specified by the guardsize parameter.

When creating a thread, use a thread attributes object to specify nondefault values for thread attributes. The guardsize attribute of a thread attributes object specifies the minimum size (in bytes) of the guard area for the stack of a new thread.

A guard area can help a multithreaded program detect overflow of a thread’s stack. A guard area is a region of no-access memory that the system allocates at the overflow end of the thread’s stack. When any thread attempts to access a memory location within this region, a memory addressing violation occurs.

A new thread can be created with the default value for the guardsize attribute. This value is platform-dependent but is always at least one "hardware protection unit" (that is, at least one page).

After this function is called, the system might reserve a larger guard area for a new thread than was specified by the guardsize parameter.

The system allows your program to specify the size of a thread stack’s guard area because:

When a thread allocates large data structures on its stack, a guard area with a size greater than the default size might be required to detect stack overflow.

Overflow protection of a thread’s stack can potentially waste system resources, such as for an application that creates a large number of threads that will never overflow their stacks. A multithreaded program can conserve system resources by specifying a guard-

size attribute of 0 (zero).

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0 Successful completion.

5

30 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_attr_setguardsize_np(2)

[EINVAL] The value specified for the attr parameter or the guardsize parameter is invalid.

RELATED INFORMATION

Functions: pthread_attr_init(2), pthread_attr_getguardsize_np(2),

pthread_attr_setstacksize(2), pthread_create(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification and to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

527186-003 Hewlett-Packard Company 5

31

pthread_attr_setinheritsched(2) OSS System Calls Reference Manual

NAME

pthread_attr_setinheritsched - Sets the inherit scheduling attribute of a thread attributes object

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_attr_setinheritsched(

pthread_attr_t *attr,

int inheritsched );

PARAMETERS

attr

specifies the address of the thread attributes object whose inherit scheduling attribute is to be set.

inheritsched

specifies the new value for the inherit scheduling attribute. Valid values are:

PTHREAD_INHERIT_SCHED

The created thread inherits the scheduling policy and associated scheduling attributes of the thread calling the pthread_create( ) function. Any scheduling attributes in the thread attributes object specified by the pthread_create( ) attr parameter are ignored during thread creation.

PTHREAD_EXPLICIT_SCHED

This is the default value. The scheduling policy and associated scheduling attributes of the created thread are set to the corresponding values from the thread attributes object specified by the pthread_create( ) attr parameter.

DESCRIPTION

This function sets the value of the inherit scheduling attribute of the thread attributes object specified by the attr parameter to the value specified by the inheritsched parameter. The inherit scheduling attribute specifies whether threads created using the specified thread attributes object inherit the scheduling attributes of the creating thread or use the scheduling attributes stored in the thread attributes object specified by the pthread_create( ) attr parameter.

The default scheduling policy for the first thread in an application is SCHED_FIFO, and cannot be modified.

Inheriting scheduling attributes is useful when a thread is creating several helper threads — that is, threads that are intended to work closely with the creating thread to cooperatively solve the same problem. For example, inherited scheduling attributes ensure that helper threads created in a sort routine execute with the same priority as the calling thread.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0

[EINVAL]

Successful completion.

The value specified by the attr parameter is not a valid thread attributes object or the inheritsched parameter contains an invalid value.

5

32 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_attr_setinheritsched(2)

[ENOTSUP] An attempt was made to set the attribute to an unsupported value.

RELATED INFORMATION

Functions: pthread_attr_init(2), *Lpthread_attr_getinheritsched(2),

pthread_attr_setschedpolicy(2), pthread_attr_setschedparam(2), pthread_create(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 5

33

pthread_attr_setschedparam(2) OSS System Calls Reference Manual

NAME

pthread_attr_setschedparam - Sets the scheduling parameters of the scheduling policy attribute of a thread attributes object

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_attr_setschedparam(

pthread_attr_t *attr,

const struct sched_param *param );

PARAMETERS

attr param

specifies the address of the thread attributes object with the scheduling policy attribute whose scheduling parameters are to be set.

specifies a structure containing the new values for the scheduling parameters.

The system provides only the sched_priority scheduling parameter. See

Description for information about this scheduling parameter.

DESCRIPTION

This function sets the values of the scheduling parameters of the scheduling policy attribute of the thread attributes object specified by the attr parameter to the values specified by the param parameter.

Use the sched_priority field of the sched_param structure to set a thread’s execution priority.

The effect of the scheduling priority you assign depends on the scheduling policy attribute of the thread attributes object specified by the attr parameter.

By default, the prioirty of a created thread is determined by the attr parameter used in the call to the pthread_create( ) function. To inherit the prioirty of the thread calling pthread_create( ), scheduling inheritance must be enabled when the thread is created. Before calling

pthread_create( ), call pthread_attr_setinheritsched( ) and specify the value

PTHREAD_INHERIT_SCHED for the inherit parameter.

An application specifies priority only to express the urgency of executing the thread relative to other threads. DO NOT USE PRIORITY TO CONTROL MUTUAL EXCLUSION WHEN

ACCESSING SHARED DATA. With a sufficient number of processors present, all ready threads, regardless of priority, execute simultaneously.

Valid values of the sched_priority scheduling parameter depend on the chosen scheduling policy. Use the sched_get_priority_min( ) and sched_get_priority_max( ) functions to determine the low and high limits of each policy.

Open System Services provides the following nonportable priority range constants:

SCHED_FIFO

PRI_FIFO_MIN to PRI_FIFO_MAX

SCHED_RR

PRI_RR_MIN to PRI_RR_MAX

SCHED_OTHER

PRI_OTHER_MIN to PRI_OTHER_MAX

5

34 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_attr_setschedparam(2)

SCHED_FG_NP

PRI_FG_MIN_NP to PRI_FG_MAX_NP

SCHED_BG_NP

PRI_BG_MIN_NP to PRI_BG_MAX_NP

The default priority is 24.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values ares:

0

[EINVAL]

Successful completion.

The value specified by the attr parameter is not a valid thread attributes object or the value specified by param is invalid.

[ENOTSUP] An attempt was made to set the attribute to an unsupported value.

RELATED INFORMATION

Functions: pthread_attr_init(2), pthread_attr_getschedparam(2),

pthread_attr_setinheritsched(2), pthread_attr_setschedpolicy(2), pthread_create(2),

sched_yield(2), sched_get_priority_max(2), sched_get_priority_min(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 5

35

pthread_attr_setschedpolicy(2) OSS System Calls Reference Manual

NAME

pthread_attr_setschedpolicy - Sets the scheduling policy attribute of a thread attributes object

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_attr_setschedpolicy(

pthread_attr_t *attr,

int policy );

PARAMETERS

attr policy

specifies the address of the thread attributes object whose scheduling policy attribute is to be set.

specifies the new value for the scheduling policy attribute. Valid values are:

SCHED_FIFO is the default value and the only value supported.

DESCRIPTION

This function sets the value of the scheduling policy attribute of the thread attributes object specified by the attr parameter to the value specified by the policy attribute. The only supported policy is SCHED_FIFO. An attempt to change this value returns the value of [ENOTSUP] for this function.

NOTES

Never attempt to use scheduling as a mechanism for synchronization.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0 Successful completion.

[EINVAL] The value specified by the policy parameter is invalid.

[ENOTSUP] An attempt was made to set the scheduling policy to an unsupported value.

RELATED INFORMATION

Functions: pthread_attr_init(2), pthread_attr_getschedpolicy(2),

pthread_attr_setinheritsched(2), pthread_attr_setschedparam(2), pthread_create(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

5

36 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_attr_setstacksize(2)

NAME

pthread_attr_setstacksize - Sets the stacksize attribute of a thread attributes object

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_attr_setstacksize(

pthread_attr_t *attr,

size_t stacksize );

PARAMETERS

attr stacksize

specifies the address of the thread attributes object whose stacksize attribute is to be set.

specifies the new value for the stacksize attribute. The stacksize parameter must be greater than or equal to PTHREAD_STACK_MIN, which is the minimum size (in bytes) of stack needed for a thread.

DESCRIPTION

This function sets the value of the stacksize attribute in the thread attributes object specified by the attr parameter to the value specified by the stacksize parameter. Use this function to adjust the size of the writable area of the stack for a new thread.

The size of a thread’s stack is fixed at the time of thread creation. Only the initial thread can dynamically extend its stack.

NOTES

Many compilers do not check for stack overflow. Ensure that the new thread’s stack is big enough for the resources required by routines that are called from the thread.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0

[EINVAL]

Successful completion.

The value specified by the attr parameter is invalid, or the value specified by the

stacksize parameter either is less than PTHREAD_STACK_MIN or exceeds a system-imposed limit.

RELATED INFORMATION

Functions: pthread_attr_init(2), pthread_attr_getstacksize(2), pthread_create(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 5

37

pthread_cancel(2) OSS System Calls Reference Manual

NAME

pthread_cancel - Requests that a thread terminate execution

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_cancel(

pthread_t thread );

PARAMETERS

thread

specifies the thread that receives the cancelation request.

DESCRIPTION

This function sends a cancelation request to the specified target thread. A cancelation request is a mechanism by which a calling thread requests the target thread to terminate as quickly as possible. Issuing a cancelation request does not guarantee that the target thread receives or handles the request.

When the cancelation request is acted on, all active cleanup-handler routines for the target thread are called. When the last cleanup handler returns, the thread-specific data destructor routines are called for each thread-specific data key with a destructor and for which the target thread has a non-NULL value. Finally, the target thread is terminated, and a status of

PTHREAD_CANCELED is made available to any threads joining with the target thread.

Cancelation of the target thread runs asynchronously to the calling thread’s returning from

pthread_cancel( ). The target thread’s cancelability state and type determine when or if the cancelation takes place, as follows:

The target thread can delay cancelation during critical operations by setting its cancelability state to PTHREAD_CANCEL_DISABLE.

Because of communication delays, the calling thread can rely only on the fact that a cancelation request eventually becomes pending in the target thread (provided that the target thread does not terminate beforehand).

The calling thread has no guarantee that a pending cancelation request will be delivered, because delivery is controlled by the target thread.

When a cancelation request is delivered to a thread, termination processing is similar to that for

pthread_exit( ). For more information about thread termination, see the pthread_create(2) reference page either online or in the Open System Services System Calls Reference Manual.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0

[ESRCH]

Successful completion.

The value of the thread parameter does not specify an existing thread.

5

38 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_cancel(2)

RELATED INFORMATION

Functions: pthread_cleanup_pop(2), pthread_cleanup_push(2), pthread_create(2),

pthread_exit(2), pthread_join(2), pthread_setcancelstate(2), pthread_setcanceltype(2),

pthread_testcancel(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 5

39

pthread_cleanup_pop(2) OSS System Calls Reference Manual

NAME

pthread_cleanup_pop - (Macro) Removes the cleanup-handler routine from the calling thread’s cleanup-handler stack and optionally executes it

LIBRARY

None. This application program interface is implemented as a macro.

SYNOPSIS

#include <spthread.h> void pthread_cleanup_pop(

int execute );

PARAMETERS

execute

controls whether the cleanup-handler routine specified in the matching call to

pthread_cleanup_push( ) is executed. If execute is nonzero, the cleanuphandler routine executes.

DESCRIPTION

This macro removes the cleanup-handler routine established by the matching call to

pthread_cleanup_push( ) from the calling thread’s cleanup-handler stack, then executes it if the value of execute is nonzero.

A cleanup-handler routine can be used to clean up from a block of code whether the code is exited by normal completion, cancelation, or the raising (or reraising) of an exception. The routine is popped from the calling thread’s cleanup-handler stack and is executed with its arg parameter when any of the following actions occur:

The thread calls pthread_cleanup_pop( ) and specifies a nonzero value for the execute parameter.

The thread calls pthread_exit( ).

The thread is canceled.

An exception is raised and is caught when the system unwinds the calling thread’s stack to the lexical scope of the pthread_cleanup_push( ) and pthread_cleanup_pop( ) macros.

This macro and pthread_cleanup_push( ) must appear in pairs within the same lexical scope.

RELATED INFORMATION

Functions: pthread_cancel(2), pthread_cleanup_push(2), pthread_create(2),

pthread_exit(2).

STANDARDS CONFORMANCE

This macro is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

5

40 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_cleanup_push(2)

NAME

pthread_cleanup_push - (Macro) Establishes a cleanup-handler routine to be executed when the thread terminates

LIBRARY

None. This application program interface is implemented as a macro.

SYNOPSIS

#include <spthread.h> void pthread_cleanup_push(

void ( *routine ) ( void * ),

void *arg );

PARAMETERS

routine arg

specifies the routine to be executed as the cleanup handler.

specifies an argument to be passed to the cleanup routine.

DESCRIPTION

This macro pushes the specified routine onto the calling thread’s cleanup- handler stack. The cleanup-handler routine is popped from the stack and executed with the value specified by the

arg parameter when any of the following actions occur:

The thread calls pthread_cleanup_pop( ) and specifies a nonzero value for the execute parameter.

The thread calls pthread_exit( ).

The thread is canceled.

An exception is raised and is caught when the system unwinds the calling thread’s stack to the lexical scope of the pthread_cleanup_push( ) and pthread_cleanup_pop( ) pair.

This routine and pthread_cleanup_pop( ) must appear in pairs within the same lexical scope.

RELATED INFORMATION

Functions: pthread_cancel(2), pthread_cleanup_pop(2), pthread_create(2), pthread_exit(2),

pthread_testcancel(2).

STANDARDS CONFORMANCE

This macro is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 5

41

pthread_cond_broadcast(2) OSS System Calls Reference Manual

NAME

pthread_cond_broadcast - Unblocks all threads that are waiting on the specified condition variable

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_cond_broadcast(

pthread_cond_t *cond );

PARAMETERS

cond

specifies a condition variable upon which the threads (to be awakened) are waiting.

DESCRIPTION

This function unblocks all threads waiting on the condition variable specified by cond. Calling this function implies that data guarded by the associated mutex has changed, so one or more waiting threads might be able to proceed. The threads that are unblocked contend for the mutex according to their respective scheduling policies (if applicable).

This function can be called by a thread regardless of whether it currently owns the mutex associated with the condition variable specified by cond. However, if predictable scheduling behavior is required, the mutex must be locked before the pthread_cond_broadcast( ) function is called.

If no threads are waiting on the specified condition variable, this function takes no action. The broadcast does not propagate to the next condition variable wait.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0

[EINVAL]

Successful completion.

The value specified by the cond parameter is invalid.

[ENOMEM] There is insufficient memory to initialize the condition variable specified by the

cond parameter.

RELATED INFORMATION

Functions: pthread_cond_destroy(2), pthread_cond_init(2), pthread_cond_signal(2),

pthread_cond_timedwait(2), pthread_cond_wait(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard. The return of

[ENOMEM] is an HP extension to the POSIX standard.

5

42 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_cond_destroy(2)

NAME

pthread_cond_destroy - Destroys a condition variable

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_cond_destroy(

pthread_cond_t *cond );

PARAMETERS

cond

specifies the condition variable to be destroyed.

DESCRIPTION

This function destroys the condition variable specified by the cond parameter. This function effectively uninitializes the condition variable. Call this function when a condition variable will no longer be referenced. Destroying a condition variable allows the system to reclaim internal memory associated with the condition variable.

It is safe to destroy an initialized condition variable upon which no threads are currently blocked.

Attempting to destroy a condition variable upon which other threads are blocked results in an error and returns the value of [EBUSY].

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0

[EBUSY]

[EINVAL]

Successful completion.

The object referenced by cond is being referenced by another thread that is currently executing pthread_cond_wait( ) or pthread_cond_timedwait( ) on the condition variable specified in cond.

The value specified by the cond parameter is invalid.

RELATED INFORMATION

Functions: pthread_cond_broadcast(2), pthread_cond_init(2), pthread_cond_signal(2),

pthread_cond_timedwait(2), pthread_cond_wait(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 5

43

pthread_cond_init(2) OSS System Calls Reference Manual

NAME

pthread_cond_init - Initializes a condition variable

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_cond_init(

pthread_cond_t *cond,

const pthread_condattr_t *attr );

PARAMETERS

cond attr

specifies the condition variable to be initialized.

specifies the condition variable attributes object that defines the characteristics of the condition variable to be initialized.

DESCRIPTION

This function initializes the condition variable specified by the cond parameter with attributes indicated by the attr parameter. If the value of attr is NULL, the default condition variable attributes are used.

A condition variable is a synchronization object used with a mutex. A mutex controls access to data that is shared among threads; a condition variable allows threads to wait for that data to enter a defined state.

Condition variables are not owned by a particular thread. Any associated storage is not automatically deallocated when the creating thread terminates.

If the default condition variable attributes are appropriate, use the macro

PTHREAD_COND_INITIALIZER to initialize statically allocated condition variables. The effect of using this macro is the same as the effect of calling pthread_cond_init( ) with an attr parameter of NULL. To call this macro, specify:

pthread_cond_t condition = PTHREAD_COND_INITIALIZER;

When statically initialized, a condition variable should not also be used in the

pthread_cond_init( ) function.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error, the condition variable is not initialized, and the contents of cond are undefined. Possible return values are:

0

[EAGAIN]

Successful completion.

One of the following conditions exists:

The system lacks the necessary resources to initialize another condition variable.

The system-imposed limit on the total number of condition variables under execution by a single user is exceeded.

5

44 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_cond_init(2)

[EBUSY] The implementation has detected an attempt to reinitialize the object indicated by cond, a previously initialized, but not yet destroyed, condition variable.

[EINVAL] The value specified by the attr parameter is invalid.

[ENOMEM] Insufficient memory exists to initialize the condition variable.

RELATED INFORMATION

Functions: pthread_cond_broadcast(2), pthread_cond_destroy(2), pthread_cond_signal(2),

pthread_cond_timedwait(2), pthread_cond_wait(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 5

45

pthread_cond_signal(2) OSS System Calls Reference Manual

NAME

pthread_cond_signal - Unblocks at least one thread that is waiting on the specified condition variable

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/systemzdllsnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_cond_signal(

pthread_cond_t *cond );

PARAMETERS

cond

specifies the condition variable to be signaled.

DESCRIPTION

This function unblocks at least one thread waiting on the condition variable specified by cond.

Calling this function implies that data guarded by the associated mutex has changed, so one of the waiting threads might be able to proceed. In general, only one thread is unblocked.

If no threads are waiting on the specified condition variable, this function takes no action. The signal does not propagate to the next condition variable wait.

The scheduling policy determines which thread is unblocked. A blocked thread is chosen in priority order, using a first-in/first-out (FIFO) algorithm within priorities.

This function can be called by a thread regardless of whether it owns the mutex associated with the condition variable specified by the cond parameter. However, if predictable scheduling behavior is required, the mutex must be locked before the pthread_cond_signal( ) function is called.

Do not call this function from within an interrupt handler.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0 Successful completion.

[EINVAL] The value specified by the cond parameter is not a valid condition variable.

[ENOMEM] There is insufficient memory to perform the requested operation.

RELATED INFORMATION

Functions: pthread_cond_broadcast(2), pthread_cond_destroy(2), pthread_cond_init(2),

pthread_cond_timedwait(2), pthread_cond_wait(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard. The return of

[ENOMEM] is an HP extension to the POSIX standard.

5

46 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_cond_signal_int_np(2)

NAME

pthread_cond_signal_int_np - Unblocks one thread that is waiting on the specified condition variable; callable only from an interrupt-handler routine

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_cond_signal_int_np(

pthread_cond_t *cond );

PARAMETERS

cond

specifies the condition variable to be signaled.

DESCRIPTION

This function unblocks one thread waiting on the condition variable specified by cond. Calling this function implies that data guarded by the associated mutex has changed, so the waiting thread might be able to proceed.

If no threads are waiting on the specified condition variable, this function takes no action. The signal does not propagate to the next condition variable wait.

The scheduling policy of the waiting threads determines which thread is unblocked. A blocked thread is chosen in priority order, using a first-in/first-out (FIFO) algorithm within priorities.

This function does not cause a thread blocked on a condition variable to resume execution immediately. The thread resumes execution at some time after the interrupt-handler routine returns.

You can call this function regardless of whether the associated mutex is locked by some other thread. Never lock a mutex from an interrupt- handler routine.

NOTES

This function allows you to signal a thread from a software interrupt handler. Do not call this function from noninterrupt code. To signal a thread from the normal noninterrupt level, use the

pthread_cond_signal( ) function.

RETURN VALUES

On successful completion, this function returns a 0 (zero). If an error condition occurs, this function returns -1 and sets errno to indicate the type of error.

ERRORS

The following error conditions can occur:

[EINVAL] The value specified by the cond parameter is not a valid condition variable.

RELATED INFORMATION

Functions: pthread_cond_broadcast(2), pthread_cond_destroy(2), pthread_cond_init(2),

pthread_cond_timedwait(2), pthread_cond_wait(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification and to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

527186-003 Hewlett-Packard Company 5

47

pthread_cond_timedwait(2) OSS System Calls Reference Manual

NAME

pthread_cond_timedwait - Causes a thread to wait either for a condition variable to be signaled or broadcast, or for a specific expiration time

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_cond_timedwait(

pthread_cond_t *cond,

pthread_mutex_t *mutex,

const struct timespec *abstime );

PARAMETERS

cond mutex abstime

specifies the condition variable that the calling thread waits on.

specifies the mutex associated with the condition variable specified by the cond parameter.

specifies the absolute time at which the wait expires, if the condition variable

cond has not been signaled or broadcast. See the

pthread_get_expiration_np(2) reference page either online or in the Open Sys-

tem Services System Calls Reference Manual; that function is used to obtain a value for this parameter. The abstime value is specified in Universal Coordinated Time (UTC).

DESCRIPTION

This function causes a thread to wait until one of the following occurs:

The specified condition variable is signaled or broadcasted.

The current system clock time is greater than or equal to the time specified by the abs-

time parameter.

This function is similar to the pthread_cond_wait( ) function, except that this function can return before a condition variable is signaled or broadcast if the specified time expires. For more information, see the pthread_cond_wait(2) reference page either online or in the Open System

Services System Calls Reference Manual.

This function atomically releases the mutex and causes the calling thread to wait on the condition variable. When the thread regains control after calling pthread_cond_timedwait( ), the mutex is locked and the thread is the owner, regardless of why the wait ended. If general cancelability is enabled, the thread reacquires the mutex (blocking for it if necessary) before the cleanup handlers are run (or before the exception is raised).

If the current time equals or exceeds the expiration time, this function returns immediately, releasing and reacquiring the mutex. This function might cause the calling thread to yield (see the sched_yield(2) reference page either online or in the Open System Services System Calls

Reference Manual). Your code should check the return status whenever this function returns and take the appropriate action. Otherwise, waiting on the condition variable can become a nonblocking loop.

Call this function after you have locked the mutex specified by mutex. The results of this function are unpredictable if this function is called before the mutex is locked.

5

48 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_cond_timedwait(2)

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0

[EINVAL]

Successful completion.

One of the following conditions exists:

The value specified by cond, mutex, or abstime is invalid.

Different mutexes are supplied for concurrent

pthread_cond_timedwait( ) operations or pthread_cond_wait( ) operations on the same condition variable.

The mutex was not owned by the calling thread at the time of the call.

[ENOMEM] The system cannot acquire the memory needed to block using a statically initialized condition variable.

[ETIMEDOUT]

The time specified by the abstime parameter expired.

RELATED INFORMATION

Functions: pthread_cond_broadcast(2), pthread_cond_destroy(2), pthread_cond_init(2),

pthread_cond_signal(2), pthread_cond_wait(2), pthread_get_expiration_np(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard. The return of

[ENOMEM] is an HP extension to the POSIX standard.

527186-003 Hewlett-Packard Company 5

49

pthread_cond_wait(2) OSS System Calls Reference Manual

NAME

pthread_cond_wait - Causes a thread to wait for the specified condition variable to be signaled or broadcast

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_cond_wait(

pthread_cond_t *cond,

pthread_mutex_t *mutex );

PARAMETERS

cond mutex

specifies the condition variable that the calling thread waits on.

specifies the mutex associated with the condition variable specified by the cond parameter.

DESCRIPTION

This function causes a thread to wait for the specified condition variable to be signaled or broadcast. Each condition corresponds to one or more Boolean relations, called a predicate, based on shared data. The calling thread waits for the data to reach a particular state for the predicate to become true. However, return from this function does not imply anything about the value of the predicate, and it should be reevaluated upon return.

This function atomically releases the mutex and causes the calling thread to wait on the condition variable. When the thread regains control after calling pthread_cond_wait( ), the mutex is locked and the thread is the owner, regardless of why the wait ended. If general cancelability is enabled, the thread reacquires the mutex (blocking for it if necessary) before the cleanup handlers are run (or before the exception is raised).

If a thread changes the state of storage protected by the mutex in such a way that a predicate associated with a condition variable might now be true, that thread must call either the

pthread_cond_signal( ) or pthread_cond_broadcast( ) function for that condition variable. If neither call is made, any thread waiting on the condition variable continues to wait.

This function might (with low probability) return when the condition variable has not been signaled or broadcast. When this occurs, the mutex is reacquired before the function returns. To handle this type of situation, enclose each call to this function in a loop that checks the predicate.

The loop documents your intent and protects against spurious wakeups while allowing correct behavior even if another thread consumes the desired state before the awakened thread runs.

Threads are not allowed to wait on the same condition variable by specifying different mutexes.

Call this function after you have locked the mutex specified by mutex. The results of this function are unpredictable if this function is called before the mutex is locked.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0 Successful completion.

5

50 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_cond_wait(2)

[EINVAL] One of the following conditions exists:

The value specified by the cond or mutex parameter is invalid.

Different mutexes are supplied for concurrent pthread_cond_wait( ) operations or pthread_cond_timedwait( ) operations on the same condition variable.

The mutex was not owned by the calling thread at the time of the call.

[ENOMEM] The system cannot acquire the memory needed to block using a statically initialized condition variable.

RELATED INFORMATION

Functions: pthread_cond_broadcast(2), pthread_cond_destroy(2), pthread_cond_init(2),

pthread_cond_signal(2), pthread_cond_timedwait(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard. The return of

[ENOMEM] is an HP extension to the POSIX standard.

527186-003 Hewlett-Packard Company 5

51

pthread_condattr_destroy(2) OSS System Calls Reference Manual

NAME

pthread_condattr_destroy - Destroys a condition variable attributes object

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_condattr_destroy(

pthread_condattr_t *attr );

PARAMETERS

attr

specifies the condition variable attributes object to be destroyed.

DESCRIPTION

This function destroys the specified condition variable attributes object by uninitializing the object.

Destroying an attributes object does not affect any condition variables that were created using that attributes object.

After this function is called, using the value of attr in a call to any function other than the

pthread_condattr_init( ) function returns an error.

NOTES

The pthread_condattr_init( ) and pthread_condattr_destroy( ) functions are provided for future expansion of the threads interface and to conform with the POSIX.1c standard. These functions are not currently useful, because the functions to set and get the process shared attribute are not supported by this implementation.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible error return values are:

0

[EINVAL]

Successful completion.

The condition variable attributes object specified by the attr parameter is invalid.

RELATED INFORMATION

Functions: pthread_condattr_init(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

5

52 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_condattr_init(2)

NAME

pthread_condattr_init - Initializes a condition variable attributes object

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_condattr_init(

pthread_condattr_t *attr );

PARAMETERS

attr

specifies the condition variable attributes object to be initialized.

If the value specified is pthread_condattr_default, then the default attribute is:

PTHREAD_PROCESS_PRIVATE

specifies that the initialized condition variable can be used only within a process.

DESCRIPTION

This function initializes the condition variable attributes object specified by the attr parameter with a set of default attribute values.

When an attributes object is used to create a condition variable, the values of the individual attributes determine the characteristics of the new condition variable. Attributes objects act as additional arguments to creation of condition variables. Changing individual attributes in an attributes object does not affect any condition variables that were previously created using that attributes object.

You can use the same condition variable attributes object in successive calls to

pthread_condattr_init( ) from any thread. If multiple threads can change attributes in a shared condition variable attributes object, your program must use a mutex to protect the integrity of the contents of that condition variable attributes object.

NOTES

The pthread_condattr_init( ) and pthread_condattr_destroy( ) functions are provided for future expansion of the threads interface and to conform with the POSIX.1c standard. These functions are not currently useful because the functions to set and get the process share attribute are not supported by this implementation.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0 Successful completion.

[ENOMEM] Insufficient memory exists to initialize the condition variable attributes object.

RELATED INFORMATION

Functions: pthread_cond_init(2), pthread_condattr_destroy(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

527186-003 Hewlett-Packard Company 5

53

pthread_condattr_init(2) OSS System Calls Reference Manual

The use of the header file spthread.h is an HP exception to the POSIX standard.

5

54 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_create(2)

NAME

pthread_create - Creates a thread

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_create(

pthread_t *thread,

const pthread_attr_t *attr,

void * ( *start_routine ) ( void * ),

void *arg );

PARAMETERS

thread attr

specifies the location to receive the identifier for the thread being created.

specifies the thread attributes object that defines the characteristics of the thread being created. If you specify NULL or pthread_attr_default, then the default attributes are:

SCHED_FIFO

The default scheduling policy for the schedpolicy attribute is first-in, first-out.

PTHREAD_CREATE_JOINABLE

The default detachstate is joinable.

A thread is detached when created if the detachstate attribute of its thread object is set to PTHREAD_CREATE_DETACHED.

start_routine

specifies the function to be executed as the new thread’s start routine.

arg

specifies the argument to the thread’s start routine.

DESCRIPTION

This function creates a thread, which is a single, sequential flow of control within a program. A thread is the active execution of a designated routine, including any nested routine invocations.

Successful execution of this function causes the following actions:

The system creates a thread object to describe and control the thread.

The thread parameter receives an identifier for the new thread.

An executable thread is created with attributes specified by the attr parameter (or with default attributes if attr is NULL).

Thread Creation

The system creates a thread in the ready state and prepares the thread to begin executing its start routine, which is the function passed to pthread_create( ) as the start_routine parameter.

Depending on the presence of other threads and their scheduling and priority attributes, the new thread might start executing immediately. The new thread can also preempt its creator, depending on the two threads’ respective scheduling and priority attributes. The caller of

pthread_create( ) can synchronize with the new thread using either the pthread_join( ) function or any mutually agreed upon mutexes or condition variables.

527186-003 Hewlett-Packard Company 5

55

pthread_create(2) OSS System Calls Reference Manual

For the duration of the new thread’s existence, the system maintains and manages the thread object and other thread state overhead.

The system assigns each new thread a thread identifier, which the system writes into the address specified by the thread parameter before the new thread executes.

At thread creation, the scheduling policy and scheduling parameters stored in the thread attributes object passed to pthread_create( ) is used by default. If you want the scheduling attributes to be inherited from the parent thread, then before creating the new thread your program must use the pthread_attr_setinheritsched( ) function with the inheritsched parameter set to

PTHREAD_INHERIT_SCHED.

The signal state of the new thread is initialized as follows:

The signal mask is inherited from the creating thread.

The set of signals pending for the new thread is empty.

If pthread_create( ) fails, no new thread is created and the contents of the location indicated by the thread parameter are undefined.

Thread Termination

A thread terminates when one of the following occurs:

The thread returns from its start routine.

The thread calls the pthread_exit( ) function.

The thread is canceled.

When a thread terminates, the system performs these actions:

The system writes a return value (if one is available) into the terminated thread’s attributes object, as follows:

— If the thread has been canceled, the system writes the value

PTHREAD_CANCELED into the object specified by attr.

— If the thread terminated by returning from its start routine, the system copies the return value from the start routine (if one is available) into the object specified by attr.

— If the thread explictly called the pthread_exit( ) function, the system stores the value received in the value_ptr parameter of pthread_exit( ) into the object specified by attr.

Another thread can obtain this return value by joining with the terminated thread using the pthread_join( ) function. If the thread terminated by returning from its start routine normally and the start routine does not provide a return value, the results obtained by joining with that thread are unpredictable.

If the termination results from a cancelation request or a call to pthread_exit( ), the system calls, in turn, each cleanup handler that this thread declared using the

pthread_cleanup_push( ) macro that has not yet been removed using the

pthread_cleanup_pop( ) macro. (The system also transfers control to any appropriate

CATCH, CATCH_ALL, or FINALLY blocks.)

For C++: At normal exit from a thread, a program calls the appropriate destructor functions, just as if an exception had been raised.

5

56 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_create(2)

To exit a thread terminated by a call to pthread_exit( ), the system raises the

pthread_exit_e exception. To exit a thread terminated by cancelation, the system raises the pthread_cancel_e exception. Your program can use the exception package to operate on the generated exception.

For each of the terminated thread’s thread-specific data keys that has a non-NULL value and a non-NULL destructor pointer, the system sets the thread’s value for the corresponding key to NULL.

In turn, the system calls each thread-specific data destructor function in this multithreaded process’s list of destructors. The destructor is given the value previously associated with the data key as its sole argument. The destructor must delete all storage associated with the data key; otherwise, the destructor will be called again.

The system repeats this step either until all thread-specific data values in the thread are

NULL or for up to a number of iterations equal to

PTHREAD_DESTRUCTOR_ITERATIONS. This action should destroy all threadspecific data associated with the terminated thread.

The system unblocks the thread (if there is one) that is currently waiting to join with the terminated thread. That is, the system unblocks the thread that is waiting in a call to

pthread_join( ).

If the thread is already detached, the system destroys its thread object. Otherwise, the thread continues to exist until it is detached or joined with.

NOTES

The practice of using CATCH handlers in place of pthread_cleanup_push( ) is not portable.

RETURN VALUES

If an error condition occurs, no thread is created, the contents of thread are undefined, and this function returns an integer value indicating the type of error. Possible return values are:

0

[EAGAIN]

[EINVAL]

Successful completion.

The system lacks the necessary resources to create another thread, or the system-imposed limit on the total number of threads under execution by a single user is exceeded.

The value specified by the attr parameter is invalid.

RELATED INFORMATION

Functions: pthread_atfork(2), pthread_attr_destroy(2), pthread_attr_init(2),

pthread_attr_setdetachstate(2), pthread_attr_setinheritsched(2),

pthread_attr_setschedparam(2), pthread_attr_setschedpolicy(2),

pthread_attr_setstacksize(2), pthread_cancel(2), pthread_cleanup_pop(2),

pthread_cleanup_push(2), pthread_detach(2), pthread_exit(2), pthread_join(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 5

57

pthread_delay_np(2) OSS System Calls Reference Manual

NAME

pthread_delay_np - Delays execution of a thread

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_delay_np(

const struct timespec *interval );

PARAMETERS

interval

specifies the number of seconds and nanoseconds to delay execution. The value specified for each must be greater than or equal to 0 (zero).

DESCRIPTION

This function causes a thread to delay execution for a specific interval of time. This interval ends at the current time plus the specified interval. The function does not return before the end of the interval is reached, but it might return an arbitrary amount of time after the end of the interval is reached, because of system load, thread priorities, and system timer granularity.

Specifying an interval of 0 (zero) seconds and 0 (zero) nanoseconds is allowed and can be used to force the thread to give up the processor or to deliver a pending cancelation request.

The timespec structure contains the following two fields:

tv_sec tv_nsec

is an integral number of seconds.

is an integral number of nanoseconds.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0

[EINVAL]

Successful completion.

The value specified by the interval parameter is invalid.

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification and to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

5

58 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_detach(2)

NAME

pthread_detach - Marks a thread object for deletion

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/ZDLLnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_detach(

pthread_t thread );

PARAMETERS

thread

specifies the thread object being marked for deletion.

DESCRIPTION

This function marks the specified thread object to indicate that storage for the corresponding thread can be reclaimed when the thread terminates. This storage includes storage for the thread parameter’s return value, as well as for the thread object. If the specified thread has not terminated when this function is called, this function does not cause it to terminate.

A thread can be created already marked for deletion by setting its thread object’s detachstate attribute using the pthread_attr_setdetachstate( ) function before creating the thread.

Once detached, the use of the thread’s thread identifier in a call to the pthread_join( ) function results in an error. A joinable thread is implicitly detached when pthread_join( ) is called.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0

[EINVAL]

[ESRCH]

Successful completion.

The thread parameter does not specify a joinable thread.

The object specified by the thread parameter cannot be found.

RELATED INFORMATION

Functions: pthread_attr_getdetachstate(2), pthread_attr_setdetachstate(2),

pthread_cancel(2), pthread_create(2), pthread_exit(2), pthread_join(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 5

59

pthread_equal(2) OSS System Calls Reference Manual

NAME

pthread_equal - Compares two thread identifiers

LIBRARY

None. This routine has been implemented as a macro.

SYNOPSIS

#include <spthread.h> int pthread_equal(

pthread_t t1,

pthread_t t2 );

PARAMETERS

t1 t2

specifies the first thread identifier to be compared.

specifies the second thread identifier to be compared.

DESCRIPTION

This function compares two thread identifiers.

NOTES

If either t1 or t2 is not a valid thread identifier, this function’s behavior is undefined.

RETURN VALUES

Possible return values are:

0

Nonzero

The t1 and t2 parameters do not designate the same object.

The t1 and t2 parameters designate the same object.

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

5

60 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_exit(2)

NAME

pthread_exit - Terminates the calling thread

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> void pthread_exit(

void *value_ptr );

PARAMETERS

value_ptr

specifies the value to be copied and returned to the caller of the pthread_join( ) function. Note that void * is used as a universal datatype, not as a pointer. The system treats the value_ptr parameter as a value and stores it to be returned by

pthread_join( ).

DESCRIPTION

This function terminates the calling thread and makes a status value (value_ptr) available to any thread that calls pthread_join( ) to join the terminating thread.

Any cleanup handlers that have been pushed and not yet popped from the stack are popped in the reverse order that they were pushed and then executed. After all cleanup handlers have been executed, if the thread has any thread-specific data, appropriate destructor functions are called.

Thread termination does not release any application-visible process resources, including, but not limited to, mutexes and file descriptors, nor does it perform any process-level cleanup actions, including, but not limited to, calling any atexit routine that might exist.

An implicit call to pthread_exit( ) is issued when a thread returns from the start routine that was used to create it. The system writes the function’s return value as the return value in the thread’s thread object. The process exits with an exit status of 0 (zero) when the last running thread calls

pthread_exit( ).

NOTES

After a thread has terminated, the result of access to local (that is, explicitly or implicitly declared auto) variables of the thread is undefined. References to local variables of the existing thread should not be used for the value_ptr parameter of the pthread_exit( ) function.

RELATED INFORMATION

Functions: pthread_cancel(2), pthread_create(2), pthread_detach(2), pthread_join(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 5

61

pthread_get_expiration_np(2) OSS System Calls Reference Manual

NAME

pthread_get_expiration_np - Calculates an absolute expiration time

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/ZDLLnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_get_expiration_np(

const struct timespec *delta,

struct timespec *abstime );

PARAMETERS

delta abstime

specifies the number of seconds and nanoseconds to add to the current system time to determine an expiration time.

receives the calculated absolute expiration time. The resulting abstime value is in Universal Coordinated Time (UTC).

DESCRIPTION

This function adds a specified interval to the current absolute system time and returns a new absolute time, which is used as the expiration time in a call to the pthread_cond_timedwait( ) function.

The timespec structure contains the following two fields:

tv_sec tv_nsec

is an integral number of seconds.

is an integral number of nanoseconds.

RETURN VALUES

On successful completion, this function returns a 0 (zero). If an error condition occurs, this function returns -1 and sets errno to indicate the type of error.

ERRORS

The following error conditions can occur:

[EINVAL] The value specified by the delta parameter is invalid.

RELATED INFORMATION

Functions: pthread_cond_timedwait(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification and to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

5

62 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_getattr_np(2)

NAME

pthread_getattr_np - Gets the attribute object for a thread

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_getattr_np (

const pthread_t thread,

pthread_attr_t **attr_p );

PARAMETERS

thread attr_p

Specifies the thread for which you want the attribute object.

Receives the attribute object pointer returned by the call.

DESCRIPTION

This fuction is used to get a thread attributes object for a specific thread. The attribute object obtained from this function call is used to set or get the individual attributes of a thread.

RETURN VALUES

This function returns 0 (zero) upon successful completion of the call. If an error occurs, this function can return the following value:

ESRCH

No thread could be found corresponding to the specified thread parameter.

RELATED INFORMATION

Functions: pthread_attr_getstacksize(2), pthread_attr_setstacksize(2),

pthread_attr_getstackaddr(2), pthread_attr_setdetachstate(2),

pthread_attr_getdetachstate(2), pthread_attr_setinheritsched(2),

pthread_attr_getinheritsched(2), pthread_attr_setschedparam(2),

pthread_attr_getschedparam(2), pthread_attr_getschedpolicy(2),

pthread_attr_setschedpolicy(2), pthread_attr_getguardsize_np(2),

pthread_attr_setguardsize_np(2), pthread_attr_init(2).

STANDARDS CONFORMANCE

Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 5

63

pthread_getconcurrency(2) OSS System Calls Reference Manual

NAME

pthread_getconcurrency - Gets level of concurrency

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_getconcurrency(void);

DESCRIPTION

Concurrency values range from 0 to MAXINT inclusive. A concurrency level of 0 suggests to the scheduler that the minimum possible amount of concurrency is required. Concurrency levels greater than 0 suggest an increasingly higher level of concurrency.

The current implementation of concurrency level (Con Levl) and the minimum scheduled quantum is as follows:

2

...

10

...

100

0

1

Con Levl

---------

Minimum Scheduled Quantum

-----------------------

Infinity

1 second

0.5 seconds

...

0.1 seconds

...

0.01 seconds

Note that the quantum is calculated using the formula, 1 / concurrency_level.

Also note that very short quantums may affect process throughput due to scheduling overhead.

RETURN VALUES

The pthread_getconcurrency( ) function always returns the concurrency level set by a previous call to pthread_setconcurrency( ). If the pthread_setconcurrency( ) function has never been called, pthread_getconcurrency( ) returns zero.

RELATED INFORMATION

Functions: pthread_setconcurrency(2).

5

64 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_getschedparam(2)

NAME

pthread_getschedparam - Obtains the current scheduling policy and scheduling parameters of a thread

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_getschedparam(

pthread_t thread,

int *policy,

struct sched_param *param );

PARAMETERS

thread policy param

specifies the thread whose scheduling policy and parameters are obtained.

receives the value of the scheduling policy for the thread specified by the thread parameter. See the pthread_setschedparam(2) reference page either online or in the Open System Services System Calls Reference Manual for valid parameter values and their meanings.

Receives the value of the scheduling parameters for the thread specified by the

thread parameter. See the pthread_setschedparam(2) reference page either online or in the Open System Services System Calls Reference Manual for valid values.

DESCRIPTION

This function obtains both the current scheduling policy and associated scheduling parameters of the thread specified by the thread parameter.

The priority value returned in the structure specified by the param parameter is the value specified in the attr parameter passed to the pthread_create( ) function or by the most recent call to the pthread_setschedparam( ) function that affected this thread.

NOTES

This function differs from the pthread_attr_getschedpolicy( ) and

pthread_attr_getschedparam( ) functions, which get the scheduling policy and parameters that are used to establish the priority and scheduling policy of a new thread when it is created.

pthread_getschedparam( ) obtains the scheduling policy and parameters of an existing thread.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values ares:

0

[ESRCH]

Successful completion.

The thread parameter does not refer to an existing thread.

RELATED INFORMATION

Functions: pthread_attr_getschedparam(2), pthread_attr_getschedpolicy(2),

pthread_create(2), pthread_self(2), pthread_setschedparam(2).

527186-003 Hewlett-Packard Company 5

65

pthread_getschedparam(2) OSS System Calls Reference Manual

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

5

66 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_getspecific(2)

NAME

pthread_getspecific - Obtains the thread-specific data associated with a key

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> void *pthread_getspecific(

pthread_key_t key );

PARAMETERS

key

specifies the context key that identifies the thread-specific data to be obtained.

DESCRIPTION

This function obtains the thread-specific data bound to the key specified by the key parameter for the calling thread. Obtain this key by calling the pthread_key_create( ) function.

This function can be called from a thread-specific data-destructor routine.

RETURN VALUES

This function returns the thread-specific data associated with key. If no thread-specific data is associated with key or if key is not defined, then this function returns a NULL value.

RELATED INFORMATION

Functions: pthread_key_create(2), pthread_setspecific(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 5

67

pthread_join(2) OSS System Calls Reference Manual

NAME

pthread_join - Causes the calling thread to wait for the termination of a thread

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_join(

pthread_t thread,

void **value_ptr);

PARAMETERS

thread value_ptr

specifies the thread whose termination is awaited by the calling thread.

receives the return value of the terminating thread.

DESCRIPTION

This function suspends execution of the calling thread until the thread specified by the thread parameter terminates.

On return from a successful pthread_join( ) call with a non-NULL value for value_ptr, the value passed to the pthread_exit( ) function is returned in the location specified by value_ptr and the terminating thread is detached.

A call to pthread_join( ) returns after the thread thread terminates.

The pthread_join( ) function is a deferred cancelation point: the thread thread is not detached if the thread blocked in pthread_join( ) is canceled. If the thread that is being joined is canceled, the pthread_join( ) function returns PTHREAD_CANCELED in the value_ptr parameter.

If the calling thread specifies itself as the thread value, [EDEADLK] is returned. A deadlock does not occur.

The pthread_join( ) or pthread_detach( ) function should eventually be called for every thread that is created with the detachstate attribute of its thread attributes object set to

PTHREAD_CREATE_JOINABLE, so that storage associated with the thread can be reclaimed.

NOTES

If more than one thread attempts to join with the same thread, the results are unpredictable.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0 Successful completion.

[EDEADLK] A deadlock was detected, or the thread parameter specifies the calling thread.

[EINVAL]

[ESRCH]

The thread parameter does not specify a joinable thread.

The thread parameter does not specify an existing thread identifier.

RELATED INFORMATION

Functions: pthread_cancel(2), pthread_create(2), pthread_detach(2), pthread_exit(2).

5

68 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_join(2)

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 5

69

pthread_key_create(2) OSS System Calls Reference Manual

NAME

pthread_key_create - Generates a unique thread-specific data key

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_key_create(

pthread_key_t *key,

void (*destructor)(void *));

PARAMETERS

key destructor

specifies the location where the new thread-specific data key is to be stored.

specifies a routine called to destroy a thread-specific data value associated with the created key when a thread terminates. The argument to the destructor for the user-specified routine is the non-NULL value associated with a key.

DESCRIPTION

This function generates a unique thread-specific data key that is visible to all threads in the process. The key provided by this function is an opaque object used to locate thread-specific data.

Although the same key value can be used by different threads, the values bound to the key by the

pthread_setspecific( ) function are maintained on a per-thread basis and persist for the life of the calling thread.

The system imposes a maximum number of thread-specific data keys, equal to the symbolic constant PTHREAD_KEYS_MAX.

Thread-specific data allows client software to associate static information with the current thread. For example, where a routine declares a variable static in a single-threaded program, a multithreaded version of the program might create a thread-specific data key to store the same variable.

This function generates and returns a new key value. The key reserves a cell within each thread.

Each call to this function creates a new cell that is unique within an application invocation. Keys must be generated from initialization code that is guaranteed to be called only once within each process. (See the pthread_once(2) reference page either online or in the Open System Services

System Calls Reference Manual for more information.)

When a thread terminates, its thread-specific data is automatically destroyed; however, the key remains unless it is destroyed by a call to the pthread_key_delete( ) function. An optional destructor routine can be associated with each key. At thread exit, if a key is associated with a non-

NULL destructor parameter, and if the thread has a non-NULL value associated with that key, the destructor routine is called with the current associated value as its only argument. The order in which thread-specific data destructors are called at thread termination is undefined.

Before each destructor routine is called, the thread’s value for the corresponding key is set to

NULL. When each destructor routine is called, the destructor must release all storage associated with the key; otherwise, the destructor will be called again. After the destructor routines have been called for all non-NULL values with associated destructor routines, if some non-NULL values with associated destructor routines still exist, then this sequence of actions is repeated.

This sequences is repeated up to PTHREAD_DESTRUCTOR_ITERATIONS times. If, after all allowed repetitions of this sequence, non-NULL values for any key with a destructor routine exist, the system terminates the thread. At this point, any key values that represent allocated heap are lost.

5

70 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_key_create(2)

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0

[EAGAIN]

Successful completion.

The system lacked the necessary resources to create another thread-specific data key, or the limit on the total number of keys for a process

(PTHREAD_KEYS_MAX) has been exceeded.

[ENOMEM] Insufficient memory exists to create the key.

RELATED INFORMATION

Functions: pthread_getspecific(2), pthread_key_delete(2), pthread_once(2),

pthread_setspecific(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 5

71

pthread_key_delete(2) OSS System Calls Reference Manual

NAME

pthread_key_delete - Deletes a thread-specific data key

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_key_delete(

pthread_key_t key);

PARAMETERS

key

specifies the thread-specific data key to be deleted.

DESCRIPTION

This function deletes the thread-specific data key specified by the key parameter, which must have been previously returned by the pthread_key_create( ) function.

The thread-specific data values associated with the specified key need not be NULL at the time this function is called. The application must free any application storage or perform any cleanup actions for data structures related to the deleted key or associated thread-specific data in any threads. This cleanup can be done either before or after this function is called.

No destructor routines are invoked by this function. Any destructor routines that might have been associated with the specified key are not called upon thread exit. pthread_key_delete( ) can be called from within destructor routines.

NOTES

Do not attempt to use the deleted key after calling this function; unpredictable behavior results.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0

[EINVAL]

Successful completion.

The value specified for the key parameter is invalid.

RELATED INFORMATION

Functions: pthread_exit(2), pthread_getspecific(2), pthread_key_create(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

5

72 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_kill(2)

NAME

pthread_kill - Sends a signal to a thread

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h>

#include <signal.h> int pthread_kill(

pthread_t thread,

int sig);

PARAMETERS

thread sig

specifies the thread to receive the signal.

specifies the signal to send. The valid values for this parameter are described in the signal(4) reference page available either online or in the Open System Ser-

vices System Calls Reference Manual.

DESCRIPTION

This function provides a mechanism for asynchronously directing a signal to a thread within the calling process. Per-thread signals have the following characteristics:

Each signal is handled in the context of the specified thread. However, the signal action

(terminating or stopping) affects the entire process.

Signal action should be manipulated using the sigaction( ) function instead of the sig-

nal( ) function.

Job control signals are not supported. The stop/continue-a-process actions implied by these signals is not supported.

Signals send using pthread_kill( ) are queued in first-in/first-out (FIFO) order for the target thread; more than one instance of the same signal can be pending for a thread. However, applications should not rely on this ordering.

The realtime signals extension option is not supported.

Whether a signal generates a saveabend file can be controled using a compiler or linker option.

If a signal is delivered to a thread that is waiting on a condition variable, upon return from the signal handler the thread resumes waiting for the condition variable as if it had not been interrupted. The thread is not unblocked with a 0 (zero) return code.

Specifying a sig value of 0 (zero) causes this function to validate the thread parameter but not to send any signal.

If this function does not execute successfully, no signal is sent.

NOTES

The name of this function is misleading, because many signals do not terminate a thread.

527186-003 Hewlett-Packard Company 5

73

pthread_kill(2) OSS System Calls Reference Manual

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0

[EINVAL]

[ESRCH]

Successful completion.

The value of the sig parameter is invalid or specifies an unsupported signal.

The thread parameter does not specify an existing thread.

RELATED INFORMATION

Functions: sigaction(2), sigwait(2). Files: signal(4).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

5

74 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_lock_global_np(2)

NAME

pthread_lock_global_np - Locks the global mutex for threads

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_lock_global_np( void);

DESCRIPTION

This function locks the threads global mutex. If the threads global mutex is currently held by another thread when this function is called, the calling thread waits for the threads global mutex to become available and then locks it.

The thread that locks the threads global mutex becomes its current owner and remains its owner until the same thread unlocks it. This function returns with the threads global mutex in the locked state and the calling thread as the threads global mutex’s current owner.

Use the threads global mutex when calling a library package that is not designed to run in a multithreaded environment. Unless documentation specifically states that a function is thread-safe, assume that the function is not compatible; in other words, assume it is nonreentrant.

The threads global mutex is one lock. Any code that calls any function that is not known to be reentrant should use the same lock to prevent problems resulting from dependencies among threads that call library functions, those functions’ calling other functions, and so on.

The threads global mutex is a recursive mutex. A thread that locks the threads global mutex can relock it without deadlocking. The locking thread must call the pthread_unlock_global_np( ) function as many times as it called this function, to allow another thread to lock the threads global mutex.

RETURN VALUES

Possible return values are as follows:

0 Successful completion.

RELATED INFORMATION

Functions: pthread_unlock_global_np(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification and to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

527186-003 Hewlett-Packard Company 5

75

pthread_mutex_destroy(2) OSS System Calls Reference Manual

NAME

pthread_mutex_destroy - Destroys a mutex

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_mutex_destroy(

pthread_mutex_t *mutex);

PARAMETERS

mutex

specifies the mutex to be destroyed.

DESCRIPTION

This function destroys the specified mutex by uninitializing it. Call this function when your program no longer needs the specified mutex object.

After this function is called, the system might reclaim the storage used by the destroyed mutex.

Destroying an initialized mutex that is unlocked is safe. Destroying a locked mutex is not allowed.

NOTES

The results of this function are unpredictable if the mutex object specified by the mutex parameter does not exist or is not initialized.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0

[EBUSY]

[EINVAL]

Successful completion.

An attempt was made to destroy the mutex indicated by the mutex parameter while it is locked or referenced.

The value specified for the mutex parameter is invalid.

RELATED INFORMATION

Functions: pthread_mutex_init(2), pthread_mutex_lock(2), pthread_mutex_trylock(2),

pthread_mutex_unlock(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

5

76 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_mutex_init(2)

NAME

pthread_mutex_init - Initializes a mutex

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_mutex_init(

pthread_mutex_t *mutex,

const pthread_mutexattr_t *attr);

PARAMETERS

mutex attr

specifies the mutex to be initialized.

specifies the mutex attributes object that defines the characteristics of the mutex to be initialized.

DESCRIPTION

This function initializes a mutex with the attributes of the mutex attributes object specified by the

attr parameter. A mutex is a synchronization object that allows multiple threads to serialize their access to shared data.

A mutex is a resource of the process, not part of any particular thread. A mutex is neither destroyed nor unlocked automatically when any thread exits. If a mutex is allocated on a stack, static initializers cannot be used on the mutex.

The mutex is initialized and set to the unlocked state. If attr is NULL, the default mutex attributes are used.

NOTES

Use the PTHREAD_MUTEX_INITIALIZER macro to statically initialize a mutex without calling this function. Use this macro as follows:

pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;

Only normal mutexes can be statically initialized.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error, the mutex is not initialized, and the contents of mutex are undefined. Possible return values are:

0

[EAGAIN]

[EBUSY]

Successful completion.

The system lacks the necessary resources to initialize the mutex.

The system detected an attempt to reinitialize a mutex (an attempt to initialize a previously initialized but not yet destroyed mutex).

The value specified by the attr parameter is invalid.

[EINVAL]

[ENOMEM] Insufficient memory exists to initialize the mutex.

[EPERM] The caller does not have the required privileges to perform the operation.

527186-003 Hewlett-Packard Company 5

77

pthread_mutex_init(2) OSS System Calls Reference Manual

RELATED INFORMATION

Functions: pthread_mutex_destroy(2), pthread_mutex_lock(2), pthread_mutex_trylock(2),

pthread_mutex_unlock(2), pthread_mutexattr_destroy(2), pthread_mutexattr_init(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

5

78 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_mutex_lock(2)

NAME

pthread_mutex_lock - Locks an unlocked mutex

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_mutex_lock(

pthread_mutex_t *mutex);

PARAMETERS

mutex

specifies the mutex to be locked.

DESCRIPTION

This function locks a mutex. The result depends upon the type of mutex:

If mutex is a fast or nonrecursive mutex, an error is returned if the current owner of the mutex calls this function in an attempt to lock the mutex a second time.

If mutex is a recursive mutex, the current owner of the mutex can relock the same mutex without blocking. The lock count is incremented for each recursive lock within the thread.

The thread that locks a mutex becomes its current owner and remains its owner until the same thread unlocks it. This function returns with the mutex in the locked state and the current thread as the mutex’s current owner.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0 Successful completion.

[EDEADLK] The current thread already owns the mutex.

[EINVAL] The value specified by the mutex parameter is not a valid mutex.

[ENOMEM] There is insufficient memory to lock a statically initialized mutex.

RELATED INFORMATION

Functions: pthread_mutex_destroy(2), pthread_mutex_init(2), pthread_mutex_trylock(2),

pthread_mutex_unlock(2).

STANDARDS CONFORMANCE

This function and recursive mutexes are an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard. The return of

[ENOMEM] is an HP extension to the POSIX standard.

527186-003 Hewlett-Packard Company 5

79

pthread_mutex_trylock(2) OSS System Calls Reference Manual

NAME

pthread_mutex_trylock - Attempts to lock a specified mutex but does not wait if the mutex is already locked

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_mutex_trylock(

pthread_mutex_t *mutex);

PARAMETERS

mutex

specifies the mutex to be locked.

DESCRIPTION

This function attempts to lock the mutex specified by the mutex parameter. When a thread calls this function, an attempt is made to immediately lock the mutex. If the mutex is successfully locked, this function returns 0 (zero) and the calling thread becomes the mutex’s current owner.

If the specified mutex is already locked, the calling thread does not wait for the mutex to become available and the function returns.

This function does the following:

If mutex is a fast or nonrecursive mutex: if the mutex is already locked by any thread

(including the calling thread) when this function is called, this function returns [EBUSY] and the calling thread does not wait to acquire the lock.

If mutex is a recursive mutex: if the mutex is either unlocked or owned by the calling thread, this function returns 0 (zero) and the mutex lock count is incremented. (To unlock a recursive mutex, each lock must be matched by a call to the

pthread_mutex_unlock( ) function.)

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0

[EBUSY]

Successful completion.

The mutex is already locked; therefore, it was not acquired.

[EINVAL] The value specified by the mutex parameter is not a valid mutex.

[ENOMEM] There is insufficient memory to lock a statically initialized mutex.

RELATED INFORMATION

Functions: pthread_mutex_destroy(2), pthread_mutex_init(2), pthread_mutex_lock(2),

pthread_mutex_unlock(2).

STANDARDS CONFORMANCE

This function and recursive mutexes are an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard. The return of

[ENOMEM] is an HP extension to the POSIX standard.

5

80 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_mutex_unlock(2)

NAME

pthread_mutex_unlock - Unlocks a mutex

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_mutex_unlock(

pthread_mutex_t *mutex);

PARAMETERS

mutex

specifies the mutex to be unlocked.

DESCRIPTION

This function unlocks the mutex specified by the mutex parameter. This function does the following:

If mutex is a fast or nonrecursive mutex: if the mutex is owned by the calling thread, it is unlocked with no current owner. If the mutex is not locked or is already locked by another thread, [EPERM] is returned.

If mutex is a recursive mutex: if the mutex is owned by the calling thread, the lock count is decremented. The mutex remains locked and owned until the lock count reaches 0

(zero). When the lock count reaches 0 (zero), the mutex becomes unlocked with no current owner.

If one or more threads are waiting to lock the specified mutex and the mutex becomes unlocked, this function causes one thread to unblock and try to acquire the mutex. The scheduling policy is used to determine which thread to unblock. A blocked thread is chosen in priority order, using a first-in/first-out (FIFO) algorithm within priorities. Note that the mutex might not be acquired by the unblocked thread if another running thread attempts to lock the mutex first.

If a signal is delivered to a thread waiting for a mutex, then upon return from the signal handler, the thread resumes waiting for the mutex as if it had not been interrupted.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0

[EINVAL]

[EPERM]

Successful completion.

The value specified for the mutex parameter is invalid.

The calling thread does not own the mutex.

RELATED INFORMATION

Functions: pthread_mutex_destroy(2), pthread_mutex_init(2), pthread_mutex_lock(2),

pthread_mutex_trylock(2).

STANDARDS CONFORMANCE

This function and recursive mutexes are an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 5

81

pthread_mutexattr_destroy(2) OSS System Calls Reference Manual

NAME

pthread_mutexattr_destroy - Destroys a mutex attributes object

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_mutexattr_destroy(

pthread_mutexattr_t *attr);

PARAMETERS

attr

specifies the mutex attributes object to be destroyed.

DESCRIPTION

This function destroys a mutex attributes object by unintializing it. Call this function when your program no longer needs the specified mutex attributes object.

After this function is called, the system might reclaim the storage used by the destroyed mutex attributes object. Destroying a mutex attributes object does not affect any mutexes that were previously created using that mutex attributes object.

NOTES

The pthread_mutexattr_init( ) and pthread_mutexattr_destroy( ) functions are provided for future expansion of the threads interface and to conform with the POSIX.1c standard. These functions are not currently useful, because the functions to set and get the process shared attribute are not supported by this implementation.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0

[EINVAL]

Successful completion.

The value specified by the attr parameter is invalid.

RELATED INFORMATION

Functions: pthread_mutexattr_init(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

5

82 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_mutexattr_getkind_np(2)

NAME

pthread_mutexattr_getkind_np - Obtains the mutex type attribute of a mutex attributes object

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> extern int pthread_mutexattr_getkind_np(

pthread_mutexattr_t attr );

PARAMETERS

attr

specifies the mutex attributes object whose mutex type is to be obtained.

DESCRIPTION

The pthread_mutexattr_getkind_np( ) function obtains the mutex type attribute of the mutex attributes object specified by the attr parameter. See the pthread_mutexattr_setkind_np(2) reference page either online or in the Open System Services System Calls Reference Manual for information about the mutex type attribute.

RETURN VALUES

One of the following values can be returned:

0

[EINVAL]

Successful completion.

The value specified by the attr parameter is invalid.

RELATED INFORMATION

Functions: pthread_mutex_init(2), pthread_mutexattr_init(2),

pthread_mutexattr_setkind_np(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification and to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

527186-003 Hewlett-Packard Company 5

83

pthread_mutexattr_init(2) OSS System Calls Reference Manual

NAME

pthread_mutexattr_init - Initializes a mutex attributes object

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_mutexattr_init(

pthread_mutexattr_t *attr);

PARAMETERS

attr

specifies the mutex attributes object to be initialized.

If the value specified is pthread_mutexattr_default, then the default attribute is:

MUTEX_FAST_NP

specifies the mutex type (normal). A normal mutex is locked exactly once by a thread. If a thread tries to lock the mutex again without first unlocking it, the thread waits for itself to release the lock and thereby deadlocks.

DESCRIPTION

This function initializes the mutex attributes object specified by the attr parameter with a set of default attribute values. A mutex attributes object is used to specify the attributes of mutexes when they are created. The mutex attributes object created by this function is used only in calls to the pthread_mutex_init( ) function.

When a mutex attributes object is used to create a mutex, the values of the individual attributes determine the characteristics of the new mutex. Thus, mutex attributes objects act as additional arguments to creation of mutexes. Changing individual attributes in a mutex attributes object does not affect any mutexes that were previously created using that mutex attributes object.

You can use the same mutex attributes object in successive calls to pthread_mutex_init( ) from any thread. If multiple threads can change attributes in a shared mutex attributes object, your program must use a mutex to protect the integrity of that mutex attributes object.

NOTES

The pthread_mutexattr_init( ) and pthread_mutexattr_destroy( ) functions are provided for future expansion of the threads interface and to conform with the POSIX.1c standard. These functions are not currently useful, because the functions to set and get the process shared attribute are not supported by this implementation.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0 Successful completion.

[ENOMEM] Not enough memory exists to initialize the mutex attributes object.

RELATED INFORMATION

Functions: pthread_mutex_init(2), pthread_mutexattr_destroy(2).

5

84 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_mutexattr_init(2)

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 5

85

pthread_mutexattr_setkind_np(2) OSS System Calls Reference Manual

NAME

pthread_mutexattr_setkind_np - Sets the mutex type attribute of a mutex attributes object

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> extern int pthread_mutexattr_setkind_np(

pthread_mutexattr_t *attr,

int kind );

PARAMETERS

attr kind

specifies the mutex attributes object whose mutex type attribute is to be modified.

specifies the new value for the mutex type attribute. Valid values are:

MUTEX_FAST_NP

This is the default value. Creates a default mutex.

MUTEX_NONRECURSIVE_NP

Creates a normal mutex.

MUTEX_RECURSIVE_NP

Creates a recursive mutex.

DESCRIPTION

The pthread_mutexattr_setkind_np( ) function sets the mutex type attribute of the mutex attributes object specified by the attr parameter.

A fast (default) mutex is locked and unlocked in the fastest manner possible. A fast mutex can be locked (obtained) only once. All subsequent calls to the pthread_mutex_lock( ) function by the owning thread return [EDEADLK]. Subsequent calls by another thread block.

A normal (nonrecursive) mutex is locked only once by a thread, like a fast (default) mutex. If the thread tries to lock the mutex again without first unlocking it, the thread receives an error. Also, if someone other than the owner tries to unlock a nonrecursive mutex, an error is returned.

A recursive mutex can be locked more than once by the same thread without returning an error.

That is, a single thread can make consecutive calls to pthread_mutex_lock( ) without blocking.

The thread must then call the pthread_mutex_unlock( ) function the same number of times as it called pthread_mutex_lock( ) before another thread can lock the mutex.

Never use a recursive mutex with condition variables, because the implicit unlock performed for a call to the pthread_cond_wait( ) or pthread_cond_timedwait( ) function might not actually release the mutex. In that case, no other thread can satisfy the condition of the predicate.

RETURN VALUES

One of the following values can be returned:

0

[EINVAL]

Successful completion.

The value specified by the attr parameter is invalid.

5

86 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_mutexattr_setkind_np(2)

[EPERM] The caller does not have the appropriate privileges to perform this operation.

[ERANGE] One or more of the parameters have an invalid value.

RELATED INFORMATION

Functions: pthread_mutex_init(2), pthread_mutexattr_getkind_np(2),

pthread_mutexattr_init(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification and to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

527186-003 Hewlett-Packard Company 5

87

pthread_once(2) OSS System Calls Reference Manual

NAME

pthread_once - Calls a routine to be executed once by a single thread

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> pthread_once_t once_control = PTHREAD_ONCE_INIT; int pthread_once(

pthread_once_t *once_control,

void ( *routine)(void) );

PARAMETERS

once_control

specifies a block that controls the one-time execution code. Each one-time execution routine must have its own unique pthread_once_t block.

routine

specifies the address of the routine to be executed once. This routine is called only once, regardless of the number of times it and its associated once_control block are passed to pthread_once( ).

DESCRIPTION

The first call to this function by any thread in a process with a given once_control block calls the routine specified by routine with no arguments. Subsequent calls to pthread_once( ) with the same once_control block do not call the routine. On return from pthread_once( ), the routine is guaranteed to have finished.

For example, a mutex or a per-thread context key must be created exactly once. Calling

pthread_once( ) ensures that the initialization is serialized across multiple threads. Other threads that reach the same point in the code are delayed until the first thread is finished.

To initialize the once_control block, use the PTHREAD_ONCE_INIT macro, as shown in the

SYNOPSIS.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0

[EINVAL]

Successful completion.

The value specified for the once_control parameter is not valid.

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

5

88 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_self(2)

NAME

pthread_self - Obtains the thread identifier of the calling thread

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> pthread_t pthread_self( void );

DESCRIPTION

This function returns the thread identifier of the calling thread.

RETURN VALUES

This function returns the thread identifier of the calling thread.

RELATED INFORMATION

Functions: pthread_cancel(2), pthread_create(2), pthread_detach(2), pthread_exit(2),

pthread_join(2), pthread_kill(2), pthread_sigmask(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 5

89

pthread_setcancelstate(2) OSS System Calls Reference Manual

NAME

pthread_setcancelstate - Sets the calling thread’s cancelability state

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_setcancelstate(

int state,

int *oldstate );

PARAMETERS

state oldstate

specifies the new cancelability state for the calling thread. Valid values are:

PTHREAD_CANCEL_ENABLE

PTHREAD_CANCEL_DISABLE

receives the previous cancelability state for the calling thread.

DESCRIPTION

This function sets the calling thread’s cancelability state to the value of the state parameter and returns its previous cancelability state in the oldstate parameter.

When the cancelability state is set to PTHREAD_CANCEL_DISABLE, a cancelation request cannot be delivered to the thread, even if a cancelable routine is called or an asynchronous cancelability type is enabled.

When a thread is created, the default cancelability state is PTHREAD_CANCEL_ENABLE.

Possible Problems When Disabling Cancelability

The most important use of thread cancelation is to ensure that possibly indefinite wait operations are terminated. For example, a thread that waits on some network connection, which can possibly take days to respond (or might never respond), should be made cancelable.

When a thread’s cancelability is disabled, no routine in that thread is cancelable. As a result, the user is unable to cancel the operation performed by that thread. When disabling cancelability, be sure that no long waits can occur and that no cancelation requests must be deferred around that particular region of code for other reasons.

RETURN VALUES

On successful completion, this function returns the calling thread’s previous cancelability state in the oldstate parameter.

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0

[EINVAL]

Successful completion.

The specified cancelability state is not PTHREAD_CANCEL_ENABLE or

PTHREAD_CANCEL_DISABLE.

RELATED INFORMATION

Functions: pthread_cancel(2), pthread_setcanceltype(2), pthread_testcancel(2).

5

90 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_setcancelstate(2)

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 5

91

pthread_setcanceltype(2) OSS System Calls Reference Manual

NAME

pthread_setcanceltype - Sets the calling thread’s cancelability type

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_setcanceltype(

int type,

int *oldtype );

PARAMETERS

type

specifies the cancelability type to set for the calling thread. Valid values are:

PTHREAD_CANCEL_DEFERRED

receives the previous cancelability type for the calling thread.

oldtype

DESCRIPTION

This function sets the calling thread’s cancelability type to the value of the type parameter and returns its previous cancelability type in the oldtype parameter.

When the cancelability state is PTHREAD_CANCEL_DISABLE (see the

pthread_setcancelstate(2) reference page either online or in the Open System Services System

Calls Reference Manual), a cancelation request cannot be delivered to the thread, even if a cancelable routine is called or the asynchronous cancelability type is enabled.

When the cancelability state is PTHREAD_CANCEL_ENABLE, cancelability depends on the thread’s cancelability type. If the thread’s cancelability type is

PTHREAD_CANCEL_DEFERRED, the thread can receive a cancelation request only at specific cancelation points (including condition waits, thread joins, and calls to the

pthread_testcancel( ) function.)

When a thread is created, the default cancelability type is PTHREAD_CANCEL_DEFERRED.

The cancelability type of PTHREAD_CANCEL_ASYNCHRONOUS is not supported in this implementation.

RETURN VALUES

On successful completion, this function returns the calling thread’s previous cancelability type in the oldtype parameter.

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0

[EINVAL]

Successful completion.

The specified type is not PTHREAD_CANCEL_DEFERRED or

PTHREAD_CANCEL_ASYNCHRONOUS.

[ENOTSUP] The specified type is PTHREAD_CANCEL_ASYNCHRONOUS.

RELATED INFORMATION

Functions: pthread_cancel(2), pthread_setcancelstate(2), pthread_testcancel(2).

5

92 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_setcanceltype(2)

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard. The use of

[ENOTSUP] is an HP extension to the POSIX standard.

527186-003 Hewlett-Packard Company 5

93

pthread_setconcurrency(2) OSS System Calls Reference Manual

NAME

pthread_setconcurrency - Sets level of concurrency

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_setconcurrency(int new_level);

DESCRIPTION

Concurrency values range from 0 to MAXINT inclusive. A concurrency level of 0 suggests to the scheduler that the minimum possible amount of concurrency is required. Concurrency levels greater than 0 suggest an increasingly higher level of concurrency.

The current implementation of concurrency level (Con Levl) and the minimum scheduled quantum is as follows:

2

...

10

...

100

0

1

Con Levl

---------

Minimum Scheduled Quantum

----------------------------

Infinity

1 second

0.5 seconds

...

0.1 seconds

...

0.01 seconds

Note that the quantum is calculated using the formula, 1 / concurrency_level.

Also note that very short quantums may affect process throughput due to scheduling overhead.

RETURN VALUES

If successful, the pthread_setconcurrency( ) function returns 0 (zero). Otherwise, an error number is returned to indicate the error.

ERRORS

The pthread_setconcurrency( ) function will fail if:

[EINVAL]

[EAGAIN]

The value specified by new_level is negative.

The value specific by new_level would cause a system resource to be exceeded.

RELATED INFORMATION

Functions: pthread_getconcurrency(2).

5

94 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_setschedparam(2)

NAME

pthread_setschedparam - Sets the scheduling policy and scheduling parameters of a thread

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_setschedparam(

pthread_t thread,

int policy,

const struct sched_param *param );

PARAMETERS

thread policy param

specifies the thread whose scheduling policy and parameters are to be set.

specifies the new scheduling policy value for the thread specified by the thread parameter. Valid values are:

SCHED_FIFO

specifies one or more new values for the scheduling parameters associated with the scheduling policy specified by the policy parameter. Valid values for the

sched_priority field of a sched_param structure depend on the chosen scheduling policy. Use the sched_get_priority_min( ) and sched_get_priority_max( ) functions to determine the low and high limits of each scheduling policy. The default priority is 24.

DESCRIPTION

This function sets both the current scheduling policy and scheduling parameters of the thread specified by the thread parameter to the policy and parameters provided by the policy and param parameters, respectively.

The scheduling policies of all threads have one scheduling attribute named sched_priority. For the scheduling policy you choose, you must specify an appropriate value in the sched_priority field of the sched_param structure.

Changing the scheduling policy, priority, or both, of a thread can cause it to start executing or to be preempted by another thread. A thread sets its own scheduling policy and priority by using the handle returned by the pthread_self( ) function.

NOTES

This function differs from the pthread_attr_setschedpolicy( ) and

pthread_attr_setschedparam( ) functions, which set the scheduling policy and scheduling parameters used to establish the priority and scheduling policy of a new thread when it is created.

However, pthread_setschedparam( ) sets the scheduling policy and scheduling parameters of an existing thread.

RETURN VALUES

If an error condition occurs, no scheduling policy or parameters are changed for the thread

thread, and this function returns an integer value indicating the type of error. Possible return values are:

0 Successful completion.

527186-003 Hewlett-Packard Company 5

95

pthread_setschedparam(2) OSS System Calls Reference Manual

[EINVAL] The value specified by the policy or param parameter is invalid.

[ENOTSUP] An attempt was made to set the scheduling policy or a scheduling parameter to an unsupported value.

[ESRCH] The thread parameter does not refer to an existing thread.

RELATED INFORMATION

Functions: pthread_attr_setschedparam(2), pthread_attr_setschedpolicy(2),

pthread_create(2), pthread_self(2), sched_yield(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface with the following exception:

[EPERM] is not returned.

The use of the header file spthread.h is an HP exception to the POSIX standard.

5

96 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_setspecific(2)

NAME

pthread_setspecific - Sets the thread-specific data associated with a key

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_setspecific(

pthread_key_t key,

const void *value );

PARAMETERS

key value

specifies the thread-specific key that identifies the thread-specific data to be set to the new value. This key value is returned by the pthread_key_create( ) function.

specifies the new thread-specific data to associate with the key specified by key.

DESCRIPTION

This function sets the thread-specific data associated with the key specified by the key parameter for the calling thread.

Different threads can bind different data to the same key. This data typically consists of pointers to blocks of dynamically allocated memory that are reserved for use by the calling thread.

Although the data type of the value parameter (void *) implies that it represents an address, the type is being used as a "universal scalar type." The system simply stores the value of value for later retrieval.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0 Successful completion.

[EINVAL] The specified key is invalid.

[ENOMEM] Insufficient memory exists to associate the new data with the key.

RELATED INFORMATION

Functions: pthread_getspecific(2), pthread_key_create(2), pthread_key_delete(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 5

97

pthread_sigmask(2) OSS System Calls Reference Manual

NAME

pthread_sigmask - Examines or changes the calling thread’s signal mask

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h>

[#include <signal.h> ]

int pthread_sigmask(

int how,

const sigset_t *set,

sigset_t *oset );

PARAMETERS

how

indicates how the set of masked signals is to be changed. Valid values are:

set

SIG_BLOCK The resulting set is the union of the previous set and the signal set indicated by the set parameter.

SIG_SETMASK

The resulting set is the signal set indicated by the set parameter.

SIG_UNBLOCK

The resulting set is the intersection of the previous signal set and the complement of the signal set indicated by the set parameter.

specifies a signal set by pointing to a set of signals used to change the blocked set. If this value is NULL, the how parameter is ignored and the signal mask is unchanged.

receives the value of the current signal mask (unless this value is NULL).

oset

DESCRIPTION

This function examines or changes the calling thread’s signal mask. Typically, you use the

SIG_BLOCK value for the how parameter to block signals during a critical section of code, and then use the SIG_SETMASK value for the how parameter to restore the signal mask to the value returned by the previous call to pthread_sigmask( ).

If any unblocked signals are pending after a call to this function, at least one of those signals is delivered before this function returns.

This function does not allow the SIGKILL or SIGSTOP signals to be blocked. If a program attempts to block one of these signals, pthread_sigmask( ) gives no indication of the error.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0

[EINVAL]

Successful completion.

The value specified for the how parameter is invalid.

5

98 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_sigmask(2)

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 5

99

pthread_testcancel(2) OSS System Calls Reference Manual

NAME

pthread_testcancel - Requests delivery of a pending cancelation request to the calling thread

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> void pthread_testcancel(void);

DESCRIPTION

This function requests delivery of a pending cancelation request to the calling thread. Thus, calling this function creates a cancelation point within the calling thread.

The cancelation request is delivered only if a request is pending for the calling thread and the calling thread’s cancelability state is enabled. (A thread disables delivery of cancelation requests to itself by calling the pthread_setcancelstate( ) function.)

When called within very long loops, this function ensures that a pending cancelation request is noticed by the calling thread within a reasonable amount of time.

RELATED INFORMATION

Functions: pthread_setcancelstate(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

5

100 Hewlett-Packard Company 527186-003

System Functions (n - p) pthread_unlock_global_np(2)

NAME

pthread_unlock_global_np - Unlocks the threads global mutex

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int pthread_unlock_global_np(void);

DESCRIPTION

This function unlocks the threads global mutex. Because the threads global mutex is recursive, the unlock occurs when the number of calls to this function match the number of calls to the

pthread_lock_global_np( ) function. For example, if you called pthread_lock_global_np( ) three times, then the third time you call pthread_unlock_global_np( ), it unlocks the threads global mutex.

If no threads are waiting for the threads global mutex, it becomes unlocked with no current owner. If one or more threads are waiting to lock the threads global mutex, this function causes one thread to unblock and try to acquire the threads global mutex. The scheduling policy determines which thread is unblocked. For the policies SCHED_FIFO and SCHED_RR, a blocked thread is chosen in priority order, using a first-in/first-out (FIFO) algorithm within priorities.

RETURN VALUES

If an error condition occurs, this function returns an integer value indicating the type of error.

Possible return values are:

0

[EPERM]

Successful completion.

The threads global mutex is unlocked or owned by another thread.

RELATED INFORMATION

Functions: pthread_lock_global_np(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification and to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

527186-003 Hewlett-Packard Company 5

101

Section 6. System Functions (r)

This section contains reference pages for Open System Services (OSS) system function calls with names that begin with r. These reference pages reside in the cat2 directory and are sorted alphabetically by U.S. English conventions in this section.

527186-003 Hewlett-Packard Company 6

1

read(2)

NAME

read - Reads from a file

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/types.h>

/* optional except for POSIX.1 */

#include <unistd.h> ssize_t read(

int filedes,

void *buffer,

size_t nbytes);

PARAMETERS

filedes buffer nbytes

Specifies an open file descriptor obtained from a successful call to the accept( ),

creat( ), dup( ), dup2( ), fcntl( ), open( ), pipe( ), socket( ), or socketpair( ) function.

Points to the buffer to receive data read.

Specifies the number of bytes to read from the file associated with the filedes parameter.

If the value of nbytes is 0 (zero), the read( ) function returns 0 (zero). There are no other results.

If the value of nbytes is greater than SSIZE_MAX, the read( ) function returns

-1 and sets errno to [EINVAL].

DESCRIPTION

The read( ) function attempts to read nbytes bytes of data from the file associated with the filedes parameter into the buffer pointed to by the buffer parameter.

On regular files and devices capable of seeking, the read( ) function starts at a position in the file given by the file pointer associated with the filedes parameter. Upon return from the read( ) function, the file pointer is incremented by the number of bytes actually read.

Devices that are incapable of seeking always read from the current position. For such devices, the value of the file pointer after a call to the read( ) function is always 0 (zero).

Upon successful completion, the read( ) function returns the number of bytes actually read and placed in the buffer. This number is never greater than the value of the nbytes parameter.

The value returned can be less than nbytes if the number of bytes left in the file is less than

nbytes, if the read( ) request was interrupted by a signal, or if the file is a pipe, FIFO file, or special file and has fewer than nbytes bytes immediately available for reading. For example, a

read( ) from a file associated with a terminal might return one typed line of data.

No data transfer occurs past the current end-of-file (EOF). If the starting position is at or after the end-of-file, 0 (zero) is returned.

If a write( ) or writev( ) call contains so much data that the file system needs to resize a pipe or

FIFO buffer, a read from that pipe or FIFO file can return up to 52 kilobytes of data, regardless of the size of PIPE_BUF. If the buffer cannot be resized for the write operation, a read from the pipe or FIFO file does not return more than 8192 bytes per call, regardless of the setting of

O_NONBLOCK.

When attempting to read from an empty pipe (or FIFO file):

6

2 Hewlett-Packard Company

OSS System Calls Reference Manual

527186-003

System Functions (r) read(2)

If no process has the pipe open for writing, the read( ) function returns the value 0 (zero) to indicate EOF.

If some process has the pipe open for writing:

— If the O_NONBLOCK flag is not set, the read( ) function blocks until either some data is written or the pipe is closed by all processes that had opened the pipe for writing.

— If the O_NONBLOCK flag is set, the read( ) function returns the value -1 and sets errno to [EAGAIN].

When attempting to read from a socket and no data is currently available:

If the O_NONBLOCK flag is not set, the read( ) function blocks until data becomes available.

If the O_NONBLOCK flag is set, the read( ) function returns the value -1 and sets errno to [EAGAIN]. The O_NONBLOCK flag has no effect if there is data available.

When attempting to read from a character special file that supports nonblocking reads, such as a terminal, and no data is currently available:

If the O_NONBLOCK flag is not set, the read( ) function blocks until data becomes available.

If the O_NONBLOCK flag is set, the read( ) function returns the value -1 and sets errno to [EAGAIN]. The O_NONBLOCK flag has no effect if there is data available.

If it is interrupted by a signal before it reads any data, the read( ) function returns the value -1 with errno set to [EINTR]. If it is interrupted by a signal after it has successfully read some data, the read( ) function returns the number of bytes read.

The read( ) function returns the number of bytes with the value 0 (zero) for any unwritten portion of a regular file prior to EOF.

When reading from a device special file, the return of EOF has no effect on subsequent calls to the read( ) function. When modem disconnect is detected, an EOF is returned. The errno variable is not set to [EIO].

Upon successful completion, the read( ) function marks the st_atime field of the file for update.

Use on Guardian Objects

After a call to the fork( ), tdm_fork( ), or tdm_spawn( ) function, the initial position within a

Guardian EDIT file (a file in /G with file code 101) is the same for both parent and child processes. However, the position is not shared. Moving the current position from within one process does not move it in the other process.

RETURN VALUES

Upon successful completion, the read( ) function returns the number of bytes actually read and placed into the buffer. The function guarantees to read the number of bytes requested only if the descriptor references a regular file that has at least that number of bytes left before EOF.

If a regular file does not contain enough bytes to satisfy the read, or if the read otherwise fails, the value -1 is returned, errno is set to indicate the error, and the contents of the buffer pointed to by the buffer parameter are indeterminate.

527186-003 Hewlett-Packard Company 6

3

read(2) OSS System Calls Reference Manual

ERRORS

If any of these conditions occurs, the read( ) function sets errno to the corresponding value:

[EAGAIN]

[EBADF]

The O_NONBLOCK flag is set for the file descriptor, and the process would be delayed in the read operation.

The O_NONBLOCK flag is set, and no data was available.

The filedes parameter is not a valid file descriptor open for reading.

[ECONNRESET]

One of these conditions occurred:

The transport-provider process for this socket is no longer available.

The TCP/IP subsystem for this socket is no longer available.

The connection was forcibly closed by the peer socket.

The file descriptor specified by the filedes parameter can only be closed.

[EFAULT] The buffer parameter points to a location outside of the allocated address space of the process.

[EFILEBAD] An attempt was made to read from a Guardian EDIT file (a file in /G with file code 101) with a corrupted internal structure.

[EINTR] A read( ) operation was interrupted by a signal before any data arrived.

[EINVAL]

[EIO]

The value of the nbytes parameter is greater than SSIZE_MAX.

One of these conditions occurred:

The process is a member of a background process group attempting to read from its controlling terminal, the process is ignoring or blocking the

SIGTTIN signal, or the process group is orphaned.

A physical I/O error occurred. Data might have been lost during a transfer.

[EISDIR] A read( ) operation was attempted against a directory.

[EISGUARDIAN]

The value used for the filedes parameter is appropriate only in the Guardian environment.

[ENETDOWN]

The filedes parameter specifies a file on a remote HP NonStop node, but communication with the remote node has been lost.

[ENOTCONN] The socket is no longer connected to a peer socket.

[ETIMEDOUT]

Data transmission on the socket timed out.

[EWRONGID] One of these conditions occurred:

The process attempted an operation through an operating system input/output process (such as a terminal server process) that has failed or is in the down state.

6

4 Hewlett-Packard Company 527186-003

System Functions (r) read(2)

The processor for the disk process of the specified file failed during an input or output operation, and takeover by the backup process occurred.

The open file descriptor has migrated to a new processor, but the new processor lacks a resource or system process needed for using the file descriptor.

The file descriptor specified by the filedes parameter can only be closed.

For all other error conditions, errno is set to the appropriate Guardian file-system error number.

See the Guardian Procedure Errors and Messages Manual for more information about a specific

Guardian file-system error.

RELATED INFORMATION

Functions: creat(2), dup(2), fcntl(2), ioctl(2), lseek(2), open(2), opendir(3), pipe(2), socket(2).

STANDARDS CONFORMANCE

The HP implementation does not return the errno value [EWOULDBLOCK] for a call on a socket that has O_NONBLOCK set when no data is available.

The POSIX standards leave some features to the implementing vendor to define. These features are affected in the HP implementation:

The value of the file pointer returned for a device that is incapable of seeking is always 0

(zero).

When reading from a device special file, the return of EOF has no effect on subsequent calls to the read( ) function.

Specifying a value for the nbytes parameter that is greater than SSIZE_MAX causes the

read( ) function to return -1 and set errno to [EINVAL].

errno can be set to [EIO] if a physical I/O error occurs.

HP extensions to the XPG4 Version 2 specification are:

The errno values [ECONNRESET], [EFAULT], [EFILEBAD], [EINVAL], [EISDIR],

[EISGUARDIAN], [ENETDOWN], [ENOTCONN], [ETIMEDOUT], and [EWRON-

GID] can be returned.

527186-003 Hewlett-Packard Company 6

5

readlink(2)

NAME

readlink - Reads the value of a symbolic link

LIBRARY

G-series native Guardian processes: system library

G-series native OSS processes: system library

H-series native Guardian processes: implicit libraries

H-series OSS processes: implicit libraries

SYNOPSIS

#include <unistd.h> int readlink(

const char *path,

char *buffer,

size_t buf_size);

PARAMETERS

path buffer buf_size

Specifies the pathname of the destination file or directory.

Points to the user’s buffer. The buffer should be at least as large as the buf_size parameter.

Specifies the size of the buffer.

If the actual length of the symbolic link is greater than the value of buf_size, the symbolic link is truncated. The buffer specified by the buffer parameter contains

buf_size bytes of the link, and the value of the buf_size parameter is returned as the value of the function.

If the actual length of the symbolic link is less than the value of buf_size, then the contents of the buffer pointed to by the buffer parameter beyond the returned value are undefined.

If the value of buf_size is 0 (zero), the contents of the buffer pointed to by the

buffer parameter are unchanged by the function call.

DESCRIPTION

The readlink( ) function places the contents of the symbolic link named by the path parameter in

buffer, which has size buf_size. If the actual length of the symbolic link is less than buf_size, the string copied into the buffer is null-terminated.

For a readlink( ) function to finish successfully, the calling process must have execute (search) permission for the directory containing the link.

Use on Guardian Objects

The readlink( ) function cannot be used on an object in the Guardian file system (/G). Symbolic links cannot be created in /G.

Use From the Guardian Environment

The readlink( ) function can be used by a Guardian process when the process has been compiled using the #define _XOPEN_SOURCE_EXTENDED 1 feature-test macro or an equivalent compiler command option.

The readlink( ) function is one of a set of functions that have the following effects when the first of them is called from the Guardian environment:

Two Guardian filesystem file numbers (not necessarily the next two available) are allocated for the root directory and the current working directory. These file numbers cannot be closed by calling the Guardian FILE_CLOSE_ procedure.

6

6 Hewlett-Packard Company

OSS System Calls Reference Manual

527186-003

System Functions (r) readlink(2)

The current working directory is assigned from the VOLUME attribute of the Guardian environment =_DEFAULTS DEFINE.

The use of static memory by the process increases slightly.

These effects occur only when the first of the set of functions is called. The effects are not cumulative.

RETURN VALUES

Upon successful completion, the readlink( ) function returns the number of characters placed in the buffer (not including any terminating null). If the readlink( ) function fails, the buffer is not modified, the value -1 is returned, and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the readlink( ) function sets errno to the corresponding value:

[EACCES] Search permission is denied on a component of the pathname prefix of the path parameter.

The path parameter points outside the process’s allocated address space.

[EFAULT]

[EFSBAD]

[EINVAL]

[EIO]

The fileset catalog for one of the filesets involved in the operation is corrupt.

The file named by the path parameter is not a symbolic link.

An I/O error occurred during a read from or write to the fileset.

[ELOOP] There were too many links encountered in translating path.

[ENAMETOOLONG]

One of the following is too long:

The pathname pointed to by the path parameter

A component of the pathname pointed to by the path parameter

The intermediate result of pathname resolution when a symbolic link is part of the path parameter

The pathconf( ) function can be called to obtain the applicable limits.

[ENOENT] One of the following conditions exists:

The file named by the path parameter does not exist.

The path parameter points to an empty string.

The path parameter specifies a file on a remote HP NonStop node but communication with the remote node has been lost.

[ENOROOT] The root fileset (fileset 0) is not in the STARTED state.

[ENOTDIR] A component of the pathname prefix of the path parameter is not a directory.

[ENXIO] An invalid device or address was specified during an input operation on a special file. One of the following events occurred:

A device was specified that does not exist, or a request was made beyond the limits of the device.

527186-003 Hewlett-Packard Company 6

7

readlink(2) OSS System Calls Reference Manual

The fileset containing the requestor’s current working directory or root directory is not mounted. This error can occur after failure and restart of an OSS name server process until the fileset has been repaired and remounted.

[EOSSNOTRUNNING]

The program attempted an operation on an object in the OSS environment while a required system process is not running.

RELATED INFORMATION

Functions: link(2), lstat(2), stat(2), symlink(2), unlink(2).

STANDARDS CONFORMANCE

The following are HP extensions to the XPG4 Version 2 specification:

The errno values [EFAULT], [EFSBAD], [ENOROOT], [ENXIO], and [EOSSNO-

TRUNNING] can be returned.

6

8 Hewlett-Packard Company 527186-003

System Functions (r) readv(2)

NAME

readv - Reads from a file into scattered buffers

LIBRARY

G-series native OSS processes: /G/system/sysnn/zossesrl

H-series OSS processes: /G/system/zdllnnn/zossedll

SYNOPSIS

#include <sys/types.h>

#include <sys/uio.h> int readv(

int filedes,

struct iovec *iov,

int iov_count);

PARAMETERS

filedes iov iov_count

Specifies an open file descriptor obtained from a successful call to the accept( ),

creat( ), dup( ), dup2( ), fcntl( ), open( ), pipe( ), socket( ), or socketpair( ) function.

Points to an iovec structure that identifies the buffers into which the data is to be placed.

Specifies the number of entries in the iovec structure pointed to by the iov parameter.

DESCRIPTION

The readv( ) function attempts to read data from the file associated with the filedes parameter into a set of buffers. The readv( ) function performs the same action as the read( ) function, but it scatters the input data into the buffers specified by the array of iovec structure entries pointed to by the iov parameter.

On regular files and devices capable of seeking, the readv( ) function starts at a position in the file given by the file pointer associated with the filedes parameter. Upon return from the readv( ) function, the file pointer is incremented by the number of bytes actually read.

Devices that are incapable of seeking always read from the current position. For such devices, the value of the file pointer after a call to the readv( ) function is always 0 (zero).

Upon successful completion, the readv( ) function returns the number of bytes actually read and placed in the buffers.

No data transfer occurs past the current end-of-file (EOF). If the starting position is at or after the end-of-file, 0 (zero) is returned.

If a write( ) or writev( ) call contains so much data that the file system needs to resize a pipe or

FIFO buffer, a read from that pipe or FIFO file can return up to 52 kilobytes of data, regardless of the size of PIPE_BUF. If the buffer cannot be resized for the write operation, a subsequent read from the pipe or FIFO file does not return more than 8192 bytes per call, regardless of the setting of O_NONBLOCK.

When attempting to read from an empty pipe (or FIFO file):

If no process has the pipe open for writing, the readv( ) function returns the value 0

(zero) to indicate EOF.

If some process has the pipe open for writing:

527186-003 Hewlett-Packard Company 6

9

readv(2) OSS System Calls Reference Manual

— If the O_NONBLOCK flag is not set, the readv( ) function blocks until either some data is written or the pipe is closed by all processes that had opened the pipe for writing.

— If the O_NONBLOCK flag is set, the readv( ) function returns the value -1 and sets errno to [EAGAIN].

When attempting to read from a socket and no data is currently available:

If the O_NONBLOCK flag is not set, the readv( ) function blocks until data becomes available.

If the O_NONBLOCK flag is set, the readv( ) function returns the value -1 and sets

errno to [EAGAIN]. The O_NONBLOCK flag has no effect if there is data available.

When attempting to read from a character special file that supports nonblocking reads, such as a terminal, and no data is currently available:

If the O_NONBLOCK flag is not set, the readv( ) function blocks until data becomes available.

If the O_NONBLOCK flag is set, the readv( ) function returns the value -1 and sets

errno to [EAGAIN]. The O_NONBLOCK flag has no effect if there is data available.

If it is interrupted by a signal before it reads any data, the readv( ) function returns the value -1 with errno set to [EINTR]. If it is interrupted by a signal after it has successfully read some data, the readv( ) function returns the number of bytes read.

When reading from a device special file, the return of EOF has no effect on subsequent calls to the readv( ) function. When modem disconnect is detected, an EOF is returned. The errno variable is not set to [EIO].

Upon successful completion, the readv( ) function marks the st_atime field of the file for update.

The iov_count parameter specifies the number of entries (buffers) in the iovec structure pointed to by the iov parameter. Each iovec entry specifies the base address and length of an area in memory where data should be placed. The readv( ) function always fills a buffer completely before proceeding to the next.

The iovec structure is defined in the sys/uio.h header file and contains entries with these members:

caddr_t iov_base; int iov_len;

Use on Guardian Objects

After a call to the fork( ), tdm_fork( ), or tdm_spawn( ) function, the initial position within a

Guardian EDIT file (a file in /G with file code 101) is the same for both parent and child processes. However, the position is not shared; moving the current position from within one process does not move it in the other process.

RETURN VALUES

Upon successful completion, the readv( ) function returns the number of bytes actually read and placed into the buffers. The function guarantees to read the number of bytes requested only if the descriptor references a regular file that has at least that number of bytes left before EOF.

If a regular file does not contain enough bytes to satisfy the read or if the read otherwise fails, the value -1 is returned, errno is set to indicate the error, and the contents of the buffers are indeterminate.

6

10 Hewlett-Packard Company 527186-003

System Functions (r) readv(2)

ERRORS

If any of these conditions occurs, the readv( ) function sets errno to the corresponding value:

[EAGAIN] One of these conditions occurred:

The O_NONBLOCK flag is set for the file descriptor, and the process would be delayed in the read operation.

The O_NONBLOCK flag is set for the file descriptor, and no data was available.

[EBADF] The filedes parameter is not a valid file descriptor open for reading.

[ECONNRESET]

One of these conditions occurred:

The transport-provider process for this socket is no longer available.

The TCP/IP subsystem for this socket is no longer available.

The connection was forcibly closed by the peer socket.

The file descriptor specified by the filedes parameter can only be closed.

[EFAULT] The iov_base memeber of the iovec structure points to a location outside of the allocated address space of the process.

[EFILEBAD] An attempt was made to read from a Guardian EDIT file (a file in /G with file code 101) with a corrupted internal structure.

[EINTR]

[EINVAL]

A readv( ) operation was interrupted by a signal before any data arrived.

One of these conditions occurred:

The sum of the iov_len values in the iov array was negative or overflowed a data item of type ssize_t.

The value of the iov_count parameter was less than or equal to 0 (zero) or greater than IOV_MAX.

[EIO] One of these conditions occurred:

The process is a member of a background process group attempting to read from its controlling terminal, the process is ignoring or blocking the

SIGTTIN signal, or the process group is orphaned.

A physical I/O error occurred. The device holding the file might be in the down state, or both processors that provide access to the device might have failed. Data might have been lost during a transfer.

[EISDIR] A readv( ) operation was attempted against a directory.

[EISGUARDIAN]

The value used for the filedes parameter is appropriate only in the Guardian environment.

527186-003 Hewlett-Packard Company 6

11

readv(2) OSS System Calls Reference Manual

[ENETDOWN]

The filedes parameter specifies a file on a remote HP NonStop node, but communication with the remote node has been lost.

[ENOTCONN] The socket is no longer connected to a peer socket.

[ETIMEDOUT]

Data transmission on the socket timed out.

[EWRONGID] One of these conditions occurred:

The process attempted an input or output operation through an operating system input/output process (such as a terminal server process) that has failed or is in the down state.

The processor for the disk process of the specified file failed during an input or output operation, and takeover by the backup process occurred.

The open file descriptor has migrated to a new processor, but the new processor lacks a resource or system process needed for use of the file descriptor.

The file descriptor specified by the filedes parameter can only be closed.

For all other error conditions, errno is set to the appropriate Guardian file-system error number.

See the Guardian Procedure Errors and Messages Manual for more information about a specific

Guardian file-system error.

RELATED INFORMATION

Functions: creat(2), dup(2), fcntl(2), ioctl(2), lseek(2), open(2), opendir(3), pipe(2), socket(2).

socketpair(2),

STANDARDS CONFORMANCE

HP extensions to the XPG4 Version 2 specification are:

The errno values [ECONNRESET], [EFAULT], [EFILEBAD], [EINVAL], [EISDIR],

[EISGUARDIAN], [ENETDOWN], [ENOTCONN], [ETIMEDOUT], and [EWRON-

GID] can be returned.

6

12 Hewlett-Packard Company 527186-003

System Functions (r) recv(2)

NAME

recv - Receives a message from a connected socket

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/socket.h> ssize_t recv(

int socket,

void *buffer,

size_t length,

int flags

);

PARAMETERS

socket buffer length flags

Specifies the file descriptor of the socket.

Points to the buffer where the message should be written.

Specifies the length in bytes of the buffer pointed to by the buffer parameter.

Is a value that controls message reception. The value of the flags parameter is formed by bitwise ORing zero or more of the following values:

MSG_OOB

Requests out-of-band data.

MSG_PEEK

Peeks at an incoming message. The data is treated as unread and the next call to the recv( ) function (or similar function) will still return this data.

DESCRIPTION

The recv( ) function receives messages from a connected socket.

For message-based sockets (sockets of type SOCK_DGRAM), the entire message must be read in one call. If a message is too long to fit in the supplied buffer and MSG_PEEK is not set in the

flags parameter, the excess bytes are discarded.

For stream-based sockets (sockets of type SOCK_STREAM), message boundaries are ignored.

For such sockets, data is returned as soon as it becomes available; no data is discarded.

If no messages are available at the socket and the socket’s file descriptor is blocking

(O_NONBLOCK is not set), the recv( ) function blocks until a message arrives. If no messages are available at the socket and the socket’s file descriptor is marked nonblocking

(O_NONBLOCK is set), the recv( ) function fails and sets errno to [EWOULDBLOCK].

NOTES

When data is available, a call to the select( ) function indicates that the file descriptor for the socket is ready for reading.

Calling the recv( ) function with a flags parameter of 0 (zero) is identical to calling the read( ) function.

RETURN VALUES

Upon successful completion, the recv( ) function returns the length of the received message in bytes. If no data is available and the peer socket has performed an orderly shutdown, then 0

(zero) is returned.

527186-003 Hewlett-Packard Company 6

13

recv(2) OSS System Calls Reference Manual

If the recv( ) function call fails, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the recv( ) function sets errno to the corresponding value:

[EBADF] The socket parameter is not a valid file descriptor.

[ECONNRESET]

One of the following conditions occurred:

The transport-provider process for this socket is no longer available.

The TCP/IP subsystem for this socket is no longer available.

The connection was forcibly closed by the peer socket.

The socket can only be closed.

[EFAULT]

[EINTR]

[EINVAL]

A user-supplied memory buffer cannot be accessed or written.

A signal interrupted the function before any data was available.

The MSG_OOB value is specified in the flags parameter and no out-of-band data is available.

An input or output error occurred.

[EIO]

[ENOBUFS] There was not enough buffer space available to complete the call. A retry at a later time might succeed.

[ENOMEM] Required memory resources were not available. A retry at a later time might succeed.

[ENOTCONN] A receive operation was attempted on a connection-oriented socket that is not connected.

[ENOTSOCK] The socket parameter does not refer to a socket.

[EOPNOTSUPP]

The specified value for the flags parameter is not supported for this socket type or protocol.

[ETIMEDOUT]

A transmission timed out on an active connection.

[EWOULDBLOCK]

The socket file descriptor is marked nonblocking (O_NONBLOCK is set) and the operation would block.

RELATED INFORMATION

Functions: read(2), recvfrom(2), recvmsg(2), select(2), send(2), sendmsg(2), sendto(2), shut-

down(2), socket(2), write(2).

STANDARDS CONFORMANCE

The HP implementation does not return the errno value [ENOSR].

The following are HP extensions to the XPG4 specification:

The errno value [ECONNRESET] can be returned when the transport-provider process is unavailable.

6

14 Hewlett-Packard Company 527186-003

System Functions (r) recv(2)

527186-003 Hewlett-Packard Company 6

15

recvfrom(2) OSS System Calls Reference Manual

NAME

recvfrom - Receives a message from a socket

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/socket.h> ssize_t recvfrom(

int socket,

void *buffer,

size_t length,

int flags,

struct sockaddr *address,

size_t *address_len

);

PARAMETERS

socket buffer length flags

Specifies the file descriptor of the socket.

Points to the buffer where the message should be written.

Specifies the length in bytes of the buffer pointed to by the buffer parameter.

Is a value that controls message reception. The value of the flags parameter is formed by bitwise ORing zero or more of the following values:

MSG_OOB

Requests out-of-band data.

MSG_PEEK

Peeks at an incoming message. The data is treated as unread and the next call to the recvfrom( ) function (or similar function) will still return this data.

address

Specifies either a null pointer or a pointer to a sockaddr structure in which the sending address is to be stored. The length and format of the address depend on the address family of the socket.

For AF_INET sockets, a pointer to the address structure sockaddr_in must be cast as a struct sockaddr. For AF_INET6 sockets, a pointer to the address structure sockaddr_in6 must be cast as a struct sockaddr. For AF_UNIX sockets, a pointer to the address structure sockaddr_un must be cast as a struct

sockaddr.

address_len

Points to a size_t data item, which, on input, specifies the length of the sockaddr structure that is pointed to by the address parameter, and, on return, specifies the length of the address stored.

DESCRIPTION

The recvfrom( ) function receives messages from a connection-oriented or connectionless socket. recvfrom( ) is normally used with connectionless sockets because it includes parameters that permit a calling program to retrieve the source address of received data.

For message-based sockets (sockets of type SOCK_DGRAM), the entire message must be read in one call. If a message is too long to fit in the supplied buffer and MSG_PEEK is not set in the

flags parameter, the excess bytes are discarded.

For stream-based sockets (sockets of type SOCK_STREAM), message boundaries are ignored.

For such sockets, data is returned as soon as it becomes available; no data is discarded.

6

16 Hewlett-Packard Company 527186-003

System Functions (r) recvfrom(2)

If no messages are available at the socket and the socket’s file descriptor is blocking

(O_NONBLOCK is not set), the recvfrom( ) function blocks until a message arrives. If no messages are available at the socket and the socket’s file descriptor is marked nonblocking

(O_NONBLOCK is set), the recvfrom( ) function fails and sets errno to [EWOULDBLOCK].

If the address parameter is not a null pointer, the source address of the received message is stored in the sockaddr structure pointed to by the address parameter, and the length of this address is stored in the object pointed to by the address_len parameter.

If the actual length of the address is greater than the length of the supplied sockaddr structure, the address is truncated when stored.

NOTES

When data is available, a call to the select( ) function indicates that the file descriptor for the socket is ready for reading.

RETURN VALUES

Upon successful completion, the recvfrom( ) function returns the length of the received message in bytes. If no data is available and the peer socket has performed an orderly shutdown, then 0

(zero) is returned.

If the recvfrom( ) function call fails, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the recvfrom( ) function sets errno to the corresponding value:

[EBADF] The socket parameter is not a valid file descriptor.

[ECONNRESET]

One of the following conditions occurred:

The transport-provider process for this socket is no longer available.

The TCP/IP subsystem for this socket is no longer available.

The connection was forcibly closed by the peer socket.

The socket can only be closed.

[EFAULT]

[EINTR]

[EINVAL]

A user-supplied memory buffer cannot be accessed or written.

A signal interrupted the function before any data was available.

The MSG_OOB value is specified in the flags parameter and no out-of-band data is available.

An input or output error occurred.

[EIO]

[ENOBUFS] There was not enough buffer space available to complete the call. A retry at a later time may succeed.

[ENOMEM] Required memory resources were not available. A retry at a later time may succeed.

[ENOTCONN] A receive operation was attempted on a connection-oriented socket that is not connected.

527186-003 Hewlett-Packard Company 6

17

recvfrom(2) OSS System Calls Reference Manual

[ENOTSOCK] The socket parameter does not refer to a socket.

[EOPNOTSUPP]

The specified value for the flags parameter is not supported for this socket type or protocol.

[ETIMEDOUT]

A transmission timed out on an active connection.

[EWOULDBLOCK]

The socket file descriptor is marked nonblocking (O_NONBLOCK is set) and the operation would block.

RELATED INFORMATION

Functions: read(2), recv(2), recvmsg(2), select(2), send(2), sendmsg(2), sendto(2), shut-

down(2), socket(2), write(2).

STANDARDS CONFORMANCE

The HP implementation does not return the errno value [ENOSR].

The following are HP extensions to the XPG4 specification:

The errno value [ECONNRESET] can be returned when the transport-provider process is not available.

6

18 Hewlett-Packard Company 527186-003

System Functions (r) recvmsg(2)

NAME

recvmsg - Receives a message from a socket using a message structure

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/socket.h> ssize_t recvmsg(

int socket,

struct msghdr *message,

int flags

);

PARAMETERS

socket message

Specifies the file descriptor of the socket.

Points to a msghdr structure containing both the buffer to store the source address and the buffers for the incoming message. The length and format of the address depend on the address family for the socket. The msg_flags member of the structure is ignored on input but might contain meaningful values on output.

For:

AF_INET sockets

A pointer in msghdr to the address structure sockaddr_in must be cast as a struct sockaddr.

AF_INET6 sockets

A pointer to the address structure sockaddr_in6 must be cast as a struct sockaddr.

AF_UNIX sockets

A pointer to the address structure sockaddr_un must be cast as a

struct sockaddr.

flags

Is a value that controls message reception. The value of the flags parameter is formed by bitwise ORing zero or more of the following values:

MSG_OOB

Requests out-of-band data.

MSG_PEEK

Peeks at an incoming message. The data is treated as unread, and the next call to the recvmsg( ) function (or a similar function) will still return this data.

DESCRIPTION

The recvmsg( ) function receives messages from a connection-oriented or connectionless socket using the msghdr structure. The recvmsg( ) function is normally used with connectionless sockets because it includes parameters that permit a calling program to retrieve the source address of the received data.

For message-based sockets (sockets of type SOCK_DGRAM), the entire message must be read in one call. If a message is too long to fit in the supplied buffer and MSG_PEEK is not set in the

flags parameter, the excess bytes are discarded, and MSG_TRUNC is set in the msg_flags field of the msghdr structure.

For stream-based sockets (sockets of type SOCK_STREAM), message boundaries are ignored.

For such sockets, data is returned as soon as it becomes available; no data is discarded.

527186-003 Hewlett-Packard Company 6

19

recvmsg(2) OSS System Calls Reference Manual

If no messages are available at the socket and the socket’s file descriptor is blocking

(O_NONBLOCK is not set), the recvmsg( ) function blocks until a message arrives. If no messages are available at the socket and the socket’s file descriptor is marked nonblocking

(O_NONBLOCK is set), the recvmsg( ) function fails and sets errno to [EWOULDBLOCK].

In the msghdr structure, the msg_name and msg_namelen members specify the source address if the socket is unconnected. If the socket is connected, the msg_name and msg_namelen members are ignored. The msg_name member can be a null pointer if no names are desired or required. The msg_iov and msg_iovlen members describe the scatter/gather locations.

Upon successful completion of the recvmsg( ) call, the value of the msg_flags member of the

msghdr structure is the bitwise OR of zero or more of the following values:

MSG_CTRUNC

Control data was truncated.

MSG_OOB

Out-of-band data was received.

MSG_TRUNC

Normal data was truncated.

In the msghdr structure, the msg_control and msg_controllen members specify the ancillary data buffer that can be used only by sockets in the AF_UNIX domain to receive file descriptors passed from another process on the same node. The msg_control member can be a null pointer if ancillary data is not desired or required. If the msg_control member is nonnull, on input the

msg_controllen member contains the size of the ancillary data buffer and on output it contains the size of the received ancillary data. If, on output, the msg_controllen member is nonzero, the ancillary data buffer contains a cmsghdr structure followed by one to sixteen file descriptors.

If recvmsg( ) is called with an ancillary data buffer and MSG_PEEK is set, the msg_controllen member is valid, but the ancillary data is not meaningful (no file descriptors are received).

Ancillary data is not discarded but remains available for the next call to recvmsg( ) where

MSG_PEEK is set.

If recvmsg( ) is called with an ancillary data buffer that is too small to hold the available file descriptors, MSG_CTRUNC is set, and the excess file descriptors are discarded.

If recvmsg( ) is called with an ancillary data buffer and one or more of the received file descriptors are unusable (perhaps because of a device error), there is no error indication until the file descriptor is used.

NOTES

When data is available, a call to the select( ) function indicates that the file descriptor for the socket is ready for reading.

RETURN VALUES

Upon successful completion, the recvmsg( ) function returns the length of the received message in bytes. If no data is available and the peer socket has performed an orderly shutdown, 0 (zero) is returned.

If the recvmsg( ) function call fails, the value -1 is returned, and errno is set to indicate the error.

ERRORS

If any of these conditions occurs, the recvmsg( ) function sets errno to the corresponding value:

[EBADF] The socket parameter is not a valid file descriptor.

6

20 Hewlett-Packard Company 527186-003

System Functions (r) recvmsg(2)

[ECONNRESET]

One of these conditions occurred:

The transport-provider process for this socket is no longer available.

The TCP/IP subsystem for this socket is no longer available.

The connection was forcibly closed by the peer socket.

The socket can only be closed.

[EFAULT] A user-supplied memory buffer cannot be accessed or written.

[EINTR]

[EINVAL]

A signal interrupted the function before any data was available.

One of these conditions occurred:

The MSG_OOB value is specified in the flags parameter, and no out-ofband data is available.

The sum of the values specified for the msg_iovlen field of the msghdr structure is too large for a data item of type ssize_t.

The socket belongs to the AF_INET or AF_INET6 domain, and the function call requested msg_control data.

The socket belongs to the AF_UNIX domain, and the size of

msg_controllen is less than the size of the cmsghdr structure plus one file descriptor.

[EIO]

[EMFILE]

An input or output error occurred.

The socket is in the AF_UNIX domain, and processing the cmsghdr structure would cause the receiving process to exceed OPEN_MAX.

[ENOBUFS] Not enough buffer space was available to complete the call. A retry at a later time might succeed.

[ENOMEM] Required memory resources were not available. A retry at a later time might succeed.

[ENOTCONN] A receive operation was attempted on a connection-oriented socket that is not connected.

[ENOTSOCK] The socket parameter does not refer to a socket.

[EOPNOTSUPP]

A specified value for the flags parameter is not supported for this socket type.

[ETIMEDOUT]

A transmission timed out on an active connection.

[EWOULDBLOCK]

The socket file descriptor is marked nonblocking (O_NONBLOCK is set), and the operation would block.

527186-003 Hewlett-Packard Company 6

21

recvmsg(2) OSS System Calls Reference Manual

RELATED INFORMATION

Functions: recv(2), recvfrom(2), select(2), send(2), sendmsg(2), sendto(2), shutdown(2),

socket(2), socketpair(2).

STANDARDS CONFORMANCE

The HP implementation does not return the errno value [ENOSR].

HP extensions to the XPG4 specification are:

The errno value [ECONNRESET] can be returned when the transport-provider process is not available.

The errno value [EMFILE] can be returned.

6

22 Hewlett-Packard Company 527186-003

System Functions (r) rename(2)

NAME

rename - Renames a file or directory

LIBRARY

G-series native Guardian processes: $SYSTEM.SYSnn.ZCRTLSRL

G-series native OSS processes: system library

H-series native Guardian processes: $SYSTEM.ZDLLnnn.ZCRTLDLL

H-series OSS processes: implicit libraries

DESCRIPTION

The C run-time library supports two variants of the rename( ) function: rename_oss( ) and

rename_guardian( ). The variants support the unique file-naming conventions and structures of the OSS and Guardian file systems, respectively.

The header file maps calls to rename( ) to the variant that matches the target compilation environment. The target environment is set with the systype pragma.

Explicit calls to the rename_oss( ) and rename_guardian( ) variants in source code are made only when the behavior of one environment is desired from the other environment.

For a description of the OSS rename( ) function and the rename_oss( ) function, see the

rename_oss(2) reference page. For a description of the Guardian rename( ) function and the

rename_guardian( ) function, see the rename_guardian(2) reference page.

527186-003 Hewlett-Packard Company 6

23

rename_guardian(2) OSS System Calls Reference Manual

NAME

rename_guardian - Renames a file (Guardian rename( ) function)

LIBRARY

G-series native Guardian processes: $SYSTEM.SYSnn.ZCRTLSRL

G-series native OSS processes: /G/system/sysnn/zcrtlsrl

H-series native Guardian processes: $SYSTEM.ZDLLnnn.ZCRTLDLL

H-series OSS processes: /G/system/zdllnnn/zcrtldll

SYNOPSIS

#include <stdio.h> int rename(

const char *from,

const char *to);

int rename_guardian(

const char *from,

const char *to);

PARAMETERS

from to

Specifies the current Guardian filename of the file to be renamed.

Specifies the new Guardian filename of the file to be renamed.

If the to parameter points to an existing file, that file is replaced by the contents of the object identified by the from parameter.

DESCRIPTION

The Guardian rename( ) function and rename_guardian( ) function rename a file within the

Guardian file system.

These functions are identical in the Guardian environment. (Refer to Interoperability Variants later in this reference page.) Unless otherwise noted, this reference page uses rename( ) to refer to both the Guardian rename( ) function and rename_guardian( ) function.

The rename( ) function cannot rename an open file.

Interoperability Variants

The C run-time library supports two variants of the rename( ) function: rename_oss( ) and

rename_guardian( ). The variants support the unique file-naming conventions and structures of the OSS and Guardian file systems, respectively.

The header file maps calls to rename( ) to the variant that matches the target compilation environment. The target environment is set with the systype pragma.

Explicit calls to the rename_oss( ) and rename_guardian( ) variants in source code are made only when the behavior of one environment is desired from the other environment.

rename_oss( ) is functionally identical to the rename( ) function of the OSS environment. It is the same as setting systype oss at compile time.

systype oss is the default setting for use of the c89 utility in the OSS environment.

rename_guardian( ) is functionally identical to the rename( ) function of the Guardian environment. It is the same as setting systype guardian at compile time.

systype guardian is the default setting for the C and C++ compilers in the Guardian environment.

To use the rename_oss( ) and rename_guardian( ) functions, specify the

_TANDEM_SOURCE feature test macro.

6

24 Hewlett-Packard Company 527186-003

System Functions (r) rename_guardian(2)

RETURN VALUES

Upon successful completion, the rename( ) function returns a 0 (zero). Otherwise, a nonzero value is returned and the name of the file is not changed.

RELATED INFORMATION

Functions: rename(2), rename_oss(2).

STANDARDS CONFORMANCE

The rename_guardian( ) function is a HP extension to the XPG4 Version 2 specification.

527186-003 Hewlett-Packard Company 6

25

rename_oss(2) OSS System Calls Reference Manual

NAME

rename_oss - Renames a file or directory (OSS rename( ) function)

LIBRARY

G-series native Guardian processes: $SYSTEM.SYSnn.ZCRTLSRL

G-series native OSS processes: system library

H-series native Guardian processes: $SYSTEM.ZDLLnnn.ZCRTLDLL

H-series OSS processes: implicit libraries

SYNOPSIS

#include <stdio.h> int rename(

const char *from,

const char *to);

int rename_oss(

const char *from,

const char *to);

PARAMETERS

from to

Identifies the file or directory to be renamed.

Identifies the new pathname of the file or directory to be renamed.

If the to parameter points to an existing file or an empty directory, that file or directory is replaced by the contents of the object identified by the from parameter. If the to parameter refers to a directory that is not empty, the function exits with an error.

DESCRIPTION

The OSS rename( ) function and rename_oss( ) function rename a directory or a file within a fileset.

These functions are identical in the OSS environment. (Refer to Interoperability Variants later in this reference page.) Unless otherwise noted, this reference page uses rename( ) to refer to both the OSS rename( ) function and rename_oss( ) function.

If the from and to parameters both refer to the same existing file, the function returns successfully and performs no other action.

For the function to finish successfully, the calling process must have write and search (execute) permission for the parent directories of the entities specified by the from and to parameters. If both the from and to parameters refer to directories, write and search (execute) permission are not required on the specified directories.

The entities specified by the from and to parameters both must be of the same type (that is, both directories or both files) and must reside on the same fileset. If the entity pointed to by the to parameter already exists, it is first removed. In that case it is guaranteed that a link specified by to will exist throughout the operation. This link refers to the file specified by either the to or from parameter before the operation began.

If the final component of the from parameter is a symbolic link, the symbolic link (not the file or directory to which it points) is renamed. If the final component of the to parameter is a symbolic link, the symbolic link is destroyed.

6

26 Hewlett-Packard Company 527186-003

System Functions (r) rename_oss(2)

If the from and to parameters specify directories, the following requirements exist:

The directory specified by the from parameter must not be an ancestor of the directory specified by the to parameter. For example, the to pathname must not contain a pathname prefix that specifies from.

The directory specified by the to parameter must be empty, except for the . (dot) and . .

(dot-dot) entries.

Upon successful completion (where a rename occurs), the function marks the st_ctime and

st_mtime fields of the parent directory of each file for update.

Use on Guardian Objects

The OSS rename( ) function can be used on Guardian files (that is, files within /G). The OSS

rename( ) function cannot be used on directories within /G. The new pathname must correspond to a Guardian permanent disk file name on the same volume, and the caller must have Guardian write access to the file.

A call to rename a file in /G is implemented as the following sequence of Guardian procedure calls:

FILE_OPEN_ with read access and shared exclusion

FILE_RENAME_

FILE_CLOSE_

Use From the Guardian Environment

The OSS rename( ) function belongs to a set of functions that have the following effects when the first of them is called from the Guardian environment:

Two Guardian file-system file numbers (not necessarily the next two available) are allocated for the root directory and the current working directory. These file numbers cannot be closed by calling the Guardian FILE_CLOSE_ procedure.

The current working directory is assigned from the VOLUME attribute of the Guardian environment =_DEFAULTS DEFINE.

The use of static memory by the process increases slightly.

These effects occur only when the first of the set of functions is called. The effects are not cumulative.

Interoperability Variants

The C run-time library supports two variants of the rename( ) function: rename_oss( ) and

rename_guardian( ). The variants support the unique file-naming conventions and structures of the OSS and Guardian file systems, respectively.

The header file maps calls to rename( ) to the variant that matches the target compilation environment. The target environment is set with the systype pragma.

Explicit calls to the rename_oss( ) and rename_guardian( ) variants in source code are made only when the behavior of one environment is desired from the other environment.

rename_oss( ) is functionally identical to the rename( ) function of the OSS environment. It is the same as setting systype oss at compile time.

systype oss is the default setting for use of the c89 utility in the OSS environment.

rename_guardian( ) is functionally identical to the rename( ) function of the Guardian environment. It is the same as setting systype guardian at compile time.

systype guardian is the default setting for the C and C++ compilers in the Guardian environment.

527186-003 Hewlett-Packard Company 6

27

rename_oss(2) OSS System Calls Reference Manual

To use the rename_oss( ) and rename_guardian( ) functions, specify the

_TANDEM_SOURCE feature-test macro.

RETURN VALUES

Upon successful completion, the rename( ) function returns the value 0 (zero). Otherwise, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the rename( ) function sets errno to the corresponding value. The file or directory name remains unchanged.

[EACCES] One of the following conditions exists:

A component of either pathname denies search permission.

One of the directories containing from or to denies write permission.

The S_ISVTX flag is set on the directory containing the file referred to by the from parameter. However, the calling process is not any of the following:

— The file owner

— The directory owner

— A process with appropriate privileges

The S_ISVTX flag is set on the directory containing an existing file referred to by the to parameter. However, the calling process is not any of the following:

[EBUSY]

— The file owner

— The directory owner

— A process with appropriate privileges

One of the following conditions occurred:

The to parameter specifies a directory that exists and is one of the following:

/G or /E

— A Guardian disk volume or process name in /G (a file with an

OSS pathname of the form /G/vol or /G/process)

— The root directory of a fileset

— The /dev directory or the lost+found file for a fileset (for example, /usr/lost+found, where /usr is the mount point for a fileset)

The from parameter specifies one of the following:

/G or /E

6

28 Hewlett-Packard Company 527186-003

System Functions (r) rename_oss(2)

/dev

/dev/tty or /dev/null

lost+found

[EEXIST]

[EFAULT]

The to parameter specifies an existing nonempty directory or an existing Guardian file (a file in /G).

Either the to or from parameter is an invalid address.

[EFSBAD] The fileset catalog for one of the filesets involved in the operation is corrupt.

[EGUARDIANOPEN]

The from parameter specifies a regular disk file on the Guardian file system (that is, a file in /G or in a directory within /G) that is already opened in exclusive mode by Enscribe.

[EINVAL] One of the following conditions exists:

The from or to parameter is not a well-formed directory.

The calling process attempted to rename . (dot) or . . (dot-dot).

The from parameter is an ancestor of the to parameter.

[EISDIR]

[ELOOP]

The to parameter specifies a directory and the from parameter specifies a filename that is not a directory.

Too many symbolic links were encountered in translating either the to or from parameter.

[ENAMETOOLONG]

One of the following is too long:

The pathname pointed to by the to parameter

The pathname pointed to by the from parameter

A component of the pathname pointed to by the to parameter

A component of the pathname pointed to by the from parameter

The intermediate result of pathname resolution when a symbolic link is part of the to or from parameter

The pathconf( ) function can be called to obtain the applicable limits.

[ENOENT] One of the following conditions exists:

The path specified by the from parameter is an empty string.

The file specified by the from parameter does not exist.

The path parameter specifies a file on a remote HP NonStop node but communication with the remote node has been lost.

527186-003 Hewlett-Packard Company 6

29

rename_oss(2) OSS System Calls Reference Manual

[ENOMEM] The system has insufficient resources to complete the operation.

[ENOROOT] One of the following conditions exists:

The root fileset of the local node (fileset 0) is not in the STARTED state.

The current root fileset for the specified file is unavailable. The OSS name server for the fileset might have failed.

The specified file is on a remote HP NonStop node and communication with the remote name server has been lost.

[ENOSPC] The directory that would contain to cannot be extended, because the fileset is out of space.

[ENOTDIR] The from parameter specifies a directory and the to parameter specifies a file (not a directory), or a component of either path is not a directory.

[ENXIO] The fileset containing the client’s current working directory or root directory is not mounted.

[EOSSNOTRUNNING]

A required system process is not running.

[EPERM] One of the following conditions exists:

The call attempted to create a file named lost+found in the root directory of an OSS fileset.

The call attempted to rename a Guardian file (that is, a file within /G) that is not a regular file. This error usually occurs when an attempt is made to rename a file as a Guardian subvolume or to rename a Guardian subvolume.

[EROFS] The requested operation requires writing in a directory on a read-only fileset.

[ETXTBSY] The file to be renamed is already busy. The file specified by the from parameter is a NonStop SQL/MP object file that is currently executing.

[EXDEV] The link specified by the to parameter and the file specified by the from parameter are on different filesets.

RELATED INFORMATION

Functions: chmod(2), link(2), mkdir(2), rename(2), rename_guardian(2), rmdir(2),

unlink(2).

Commands: chmod(1), mkdir(1), mv(1).

STANDARDS CONFORMANCE

The POSIX standards leave some features to the implementing vendor to define. The following features are affected in the HP implementation:

The calling process is not required to have write or search permission for a directory in order to rename the directory.

The errno value [EBUSY] is returned when either directory is in use by another process.

6

30 Hewlett-Packard Company 527186-003

System Functions (r) rename_oss(2)

The errno value [EMLINK] is not returned, because links to directories are not allowed.

The following are HP extensions to the XPG4 Version 2 specification:

The errno values [EFAULT], [EFSBAD], [EGUARDIANOPEN], [ENOMEM],

[ENOROOT], [ENXIO], [EOSSNOTRUNNING], [EPERM], and [EXDEV] can be returned.

The rename_oss( ) function is a HP extension to the XPG4 Version 2 specification.

527186-003 Hewlett-Packard Company 6

31

rmdir(2) OSS System Calls Reference Manual

NAME

rmdir - Removes a directory

LIBRARY

G-series native Guardian processes: system library

G-series native OSS processes: system library

H-series native Guardian processes: implicit libraries

H-series OSS processes: implicit libraries

SYNOPSIS

#include <unistd.h> int rmdir(

const char *path);

PARAMETERS

path

Specifies the directory pathname. The pathname cannot be specified as . (dot) or

. . (dot-dot). If either value is used, the call fails and errno is set to [EINVAL].

The final component of the path parameter cannot be a symbolic link. If the final component is a symbolic link, the call fails and errno is set to [ENOTDIR].

DESCRIPTION

The rmdir( ) function removes the directory specified by the path parameter. The directory is removed only if it is an empty directory.

For the rmdir( ) function to execute successfully, the calling process must have write access to the parent directory of the directory specified by the path parameter.

If no process has the directory open, the space occupied by the directory is freed and the directory is no longer accessible. If one or more processes have the specified directory open, the .

(dot) and . . (dot-dot) entries in the specified directory, if present, are removed before the rmdir( ) function returns, and no new entries can be created in the directory. However, the directory is not removed until all references to the directory have been closed.

The rmdir( ) function can be used to remove a root directory (/ cannot be removed) or the current working directory of a process. However, such an action has the following consequence:

If the root directory of a process is removed, subsequent attempts by that process to resolve absolute pathnames will fail with errno set to [ENOENT].

If the current working directory of a process is removed, subsequent attempts by that process to resolve relative pathnames will fail with errno set to [ENOENT].

If the directory specified by the path parameter is any of the following, the operation fails and

errno is set to [EBUSY]:

/E or /G (the Guardian file system)

A disk volume or process within /G (/G/vol or /G/process)

A mount point for a fileset

lost+found in the root directory of a fileset

Upon successful completion, the rmdir( ) function marks the st_ctime and st_mtime fields of the parent directory for update.

Because directories can have only one link, a successful call to the rmdir( ) function always sets the link count to 0 (zero).

6

32 Hewlett-Packard Company 527186-003

System Functions (r) rmdir(2)

Use From the Guardian Environment

The rmdir( ) function is one of a set of functions that have the following effects when the first of them is called from the Guardian environment:

Two Guardian file system file numbers (not necessarily the next two available) are allocated for the root directory and the current working directory. These file numbers cannot be closed by calling the Guardian FILE_CLOSE_ procedure.

The current working directory is assigned from the VOLUME attribute of the Guardian environment =_DEFAULTS DEFINE.

The use of static memory by the process increases slightly.

These effects occur only when the first of the set of functions is called. The effects are not cumulative.

RETURN VALUES

Upon successful completion, the rmdir( ) function returns the value 0 (zero). If the rmdir( ) function fails, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the rmdir( ) function sets errno to the corresponding value:

[EACCES] One of the following conditions exists:

Search permission is denied on a component of the directory pathname specified by the path parameter.

Write permission is denied on the parent directory of the directory to be removed.

The S_ISVTX flag is set on the directory containing the directory referred to by the path parameter. However, the calling process is not any of the following:

[EBUSY]

[EFAULT]

— The parent directory owner

— The directory owner

— A process with appropriate privileges

One of the following conditions exists:

The directory specified by the path parameter is in use as the mount point for a fileset.

The directory specified by the path parameter is /E or /G (the Guardian file system) or a disk volume or process within /G (has an OSS pathname of the form /G/vol or /G/process).

The directory specified by the path parameter is the lost+found directory in the root directory for a fileset.

The path parameter is an invalid address.

527186-003 Hewlett-Packard Company 6

33

rmdir(2) OSS System Calls Reference Manual

[EFSBAD]

[EINVAL]

[EIO]

The fileset catalog for one of the filesets involved in the operation is corrupt.

The specified . (dot) or . . (dot-dot) pathname cannot be removed.

During a read from or write to a fileset, an I/O error occurred.

[ELOOP] Too many symbolic links were encountered in translating the path parameter.

[ENAMETOOLONG]

One of the following is too long:

The pathname pointed to by the path parameter

A component of the pathname pointed to by the path parameter

The intermediate result of pathname resolution when a symbolic link is part of the path parameter

The pathconf( ) function can be called to obtain the applicable limits.

[ENOENT] One of the following conditions exists:

The directory specified by the path parameter does not exist.

The path parameter specifies an empty string.

The path parameter specifies a file on a remote HP NonStop node but communication with the remote node has been lost.

[ENOROOT] One of the following conditions exists:

The root fileset of the local node (fileset 0) is not in the STARTED state.

The current root fileset for the specified file is unavailable. The OSS name server for the fileset might have failed.

The specified file is on a remote HP NonStop node and communication with the remote name server has been lost.

[ENOTDIR] One of the following conditions exists:

A component of the directory pathname specified by the path parameter is not a directory.

The final component of the path parameter is a symbolic link.

[ENOTEMPTY]

The directory specified by the path parameter is not empty.

[ENXIO] The fileset containing the client’s current working directory or root directory is not mounted.

[EOSSNOTRUNNING]

A required OSS system process is not running.

[EROFS] The directory specified by the path parameter resides on a read-only fileset.

6

34 Hewlett-Packard Company 527186-003

System Functions (r) rmdir(2)

RELATED INFORMATION

Functions: chmod(2), chroot(2), mkdir(2), mkfifo(3), mknod(2), remove(3), rename(2),

umask(2), unlink(2).

Commands: rmdir(1).

STANDARDS CONFORMANCE

The POSIX standards leave some features to the implementing vendor to define. The following features are affected in the HP implementation:

The rmdir( ) function can be used to remove the root directory or the current working directory of a process. The consequences of such an action are described under

DESCRIPTION.

The errno value [ENOTEMPTY] is returned instead of [EEXIST].

The following are HP extensions to the XPG4 Version 2 specification:

The errno values [EFAULT], [EFSBAD], [EINVAL], [ENOROOT], [ENOTEMPTY],

[ENXIO], and [EOSSNOTRUNNING] can be returned.

527186-003 Hewlett-Packard Company 6

35

Section 7. System Functions (s and S)

This section contains reference pages for Open System Services (OSS) system function calls with names that begin with s or S. These reference pages reside in the cat2 or cat3 directory and are sorted alphabetically by U.S. English conventions in this section.

527186-003 Hewlett-Packard Company 7

1

sched_get_priority_max(2) OSS System Calls Reference Manual

NAME

sched_get_priority_max - Returns the maximum priority for a scheduling policy

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/systemzdllsnnn/zsptdll

SYNOPSIS

[ #include <sched.h> ]

#include <spthread.h> int sched_get_priority_max (

int policy );

PARAMETERS

policy

specifies one of the scheduling policies defined in the sched.h header file.

DESCRIPTION

The sched_get_priority_max( ) function returns the maximum priority for the scheduling policy specified by the policy parameter. The value of policy must be one of the scheduling policies

(SCHED_FIFO, SCHED_RR, or SCHED_OTHER) defined in the sched.h header file.

No special privileges are needed to use the sched_get_priority_max( ) function.

RETURN VALUES

On a successful call, the requested value is returned. If a call fails, a value of -1 is returned and

errno is set to indicate the error.

ERRORS

The sched_get_priority_max( ) function fails under the following condition:

[EINVAL] The value of the policy parameter does not represent a defined scheduling policy.

RELATED INFORMATION

Functions: sched_get_priority_min(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1b-1993, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

2 Hewlett-Packard Company 527186-003

System Functions (s and S) sched_get_priority_min(2)

NAME

sched_get_priority_min - Returns the minimum priority for a scheduling policy

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

[ #include <sched.h> ]

#include <spthread.h> int sched_get_priority_min (

int policy );

PARAMETERS

policy

specifies one of the scheduling policies defined in the sched.h header file.

DESCRIPTION

The sched_get_priority_min( ) function returns the minimum priority for the scheduling policy specified by the policy parameter. The value of policy must be one of the scheduling policies

(SCHED_FIFO, SCHED_RR, or SCHED_OTHER) defined in the sched.h header file.

No special privileges are needed to use the sched_get_priority_min( ) function.

RETURN VALUES

On a successful call, the requested value is returned. If the call fails, a value of -1 is returned and

errno is set to indicate the error.

ERRORS

The sched_get_priority_min( ) function fails under the following condition:

[EINVAL] The value of the policy parameter does not represent a defined scheduling policy.

RELATED INFORMATION

Functions: sched_get_priority_max(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1b-1993, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

3

sched_yield(2) OSS System Calls Reference Manual

NAME

sched_yield - Signals a willingness to yield the processor to another thread in the current process

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

[#include <sched.h> ]

#include <spthread.h> int sched_yield(void);

DESCRIPTION

This function forces the calling thread to relinquish its processor until it again becomes the head of its thread list. This function notifies the thread scheduler that the calling thread is willing to release its processor to other threads of equivalent or greater scheduling precedence. (A thread generally releases its processor to a thread of a greater scheduling precedence without calling this function.) If no other threads of equivalent or greater scheduling precedence are ready to execute, the calling thread continues.

This function can allow you to use knowledge of the details of an application to improve its performance. If a thread does not call sched_yield( ), other threads might be given the opportunity to run at arbitrary points (possibly even when the interrupted thread holds a required resource).

By making strategic calls to sched_yield( ), other threads can be given the opportunity to run when the resources are free, which can sometimes improve performance by reducing contention for resources.

Consider calling this function after a thread has released a resource (such as a mutex) that is heavily used by other threads. This call can be especially important if the thread acquires and releases the resource inside a tight loop.

Use this function carefully and sparingly, because misuse can cause unnecessary context switching, which increases overhead and degrades performance. For example, performance is degraded if a thread yields while it holds a resource needed by the threads it is yielding to. Likewise, yielding is pointless unless another thread is ready to run.

RETURN VALUES

Upon successful completion, this function returns a 0 (zero).

RELATED INFORMATION

Functions: pthread_attr_setschedparam(2), pthread_setschedparam(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

4 Hewlett-Packard Company 527186-003

System Functions (s and S) select(2)

NAME

select - Selects among file descriptors for synchronous input/output multiplexing

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/time.h> int select(

int nfds,

fd_set *readfds,

fd_set *writefds,

fd_set *errorfds,

struct timeval *timeout);

void FD_CLR(

int fd,

fd_set *fdset);

int FD_ISSET(

int fd,

fd_set *fdset);

void FD_SET(

int fd,

fd_set *fdset);

void FD_ZERO(

fd_set *fdset);

PARAMETERS

nfds readfds writefds errorfds timeout

Specifies the number of open file descriptors that might be ready for reading or writing or that have exceptions pending. The nfds parameter cannot be greater than FD_SETSIZE.

Points to a file descriptor set consisting of file descriptors of objects opened for reading. When the function is called, this file descriptor set specifies file descriptors to be checked for being ready to read. Upon return from a successful call, this file descriptor set specifies file descriptors that are ready to be read.

Points to a file descriptor set consisting of file descriptors for objects opened for writing. When the function is called, this file descriptor set specifies file descriptors to be checked for being ready to write. Upon return from a successful call, this file descriptor set specifies file descriptors that are ready to be written.

Points to a file descriptor set consisting of file descriptors for objects opened for reading or writing that have an exception pending. When the function is called, this file descriptor set specifies file descriptors to be checked for having error conditions pending. Upon return from a successful call, this file descriptor set specifies file descriptors that have error conditions pending.

Points to a type timeval structure that specifies the time to wait for a response from a call to the select( ) function. When the timeout parameter is not a null pointer, the maximum time interval to wait for the select( ) function to finish is specified by values stored in space reserved by the type timeval structure pointed to by the timeout parameter.

The object pointed to by the timeout parameter can be modified after successful

527186-003 Hewlett-Packard Company 7

5

select(2) OSS System Calls Reference Manual

fd fdset

completion of the call.

Specifies a file descriptor.

Points to a file descriptor set.

DESCRIPTION

The select( ) function checks the status of objects identified by bit masks called file descriptor sets.

Each file descriptor set consists of an array of bits whose relative position and state represent a file descriptor and the true or false status for the condition of its corresponding object. An object is an open file descriptor for an OSS directory (that is, a directory that is not in /G or /E), a socket, a regular file, a pipe, or a FIFO.

There is a file descriptor set for reading, for writing, and for pending exceptions. These file descriptor sets are pointed to by the readfds, writefds, and errorfds parameters, respectively.

When the select( ) function is called, it checks the file descriptor sets in the range 0 through

nfds-1. If there is reading, writing, or an exception, the select( ) function returns a modified file descriptor set.

If no condition is true for any specified file descriptor in any specified file descriptor set, the

select( ) function blocks signals until one of these conditions occurs:

A specified condition is true for one of the specified descriptors in one of the specified sets.

The interval specified by the timeout parameter elapses. If the timeout parameter points to a structure whose members have the value 0 (zero), signal blocking does not occur.

A modified file descriptor set has these characteristics:

It is a selected file descriptor set pointed to by the readfds, writefds, and errorfds parameters.

When the function was called, the file descriptor set had at least one bit set that corresponded to an active file descriptor.

The object represented by the set bit is any of these:

— ready for reading

— ready for writing

— has an exception pending

When these conditions exist, a corresponding bit position is set in the returned file descriptor set pointed to by the readfds, writefds, and errorfds parameters.

On return, the select( ) function replaces the original file descriptor sets with the corresponding file descriptor sets that have a bit set for each file descriptor representing those objects that are ready for the requested operation. The total number of ready objects represented by set bits in all the file descriptor sets is returned by the select( ) function.

7

6 Hewlett-Packard Company 527186-003

System Functions (s and S) select(2)

After a file descriptor set is created, it can be modified with these macros:

FD_CLR(fd, &fdset)

Clears the file descriptor bit specified by the fd parameter in the file descriptor set pointed to by the fdset parameter.

FD_ISSET(fd, &fdset)

Returns a nonzero value when the file descriptor bit specified by the fd parameter is set in the file descriptor set pointed to by the fdset parameter. Otherwise, the value 0 (zero) is returned.

FD_SET(fd, &fdset)

Includes the particular file descriptor bit specified by the fd parameter in the file descriptor set pointed to by the fdset parameter.

FD_ZERO(&fdset)

Initializes the file descriptor set pointed to by the fdset parameter to a null value.

The behavior of these macros is undefined when the fd parameter has a value less than 0 (zero) or greater than or equal to FD_SETSIZE.

Use on Guardian Objects

The select( ) function can be used on regular files (disk files) or EDIT files in /G. Such files are always ready for selection.

The select( ) function can be used on a Telserv or OSSTTY terminal process. The select( ) function cannot be used on any other type of Guardian object.

Use From the Guardian Environment

The select( ) function is one of a set of functions that have these effects when the first of them is called from the Guardian environment:

Two Guardian file system file numbers (not necessarily the next two available) are allocated for the root directory and the current working directory. These file numbers cannot be closed by calling the Guardian FILE_CLOSE_ procedure.

The current working directory is assigned from the VOLUME attribute of the Guardian environment =_DEFAULTS DEFINE.

The use of static memory by the process increases slightly.

These effects occur only when the first of the set of functions is called. The effects are not cumulative.

NOTES

The select( ) function cannot be used on terminal device files (ttys) in the HP implementation.

Beginning with the G06.26 release version update (RVU), FD_SETSIZE was increased. Applications that use a variable select( ) limit based on the highest numbered file descriptor run corrrectly on both prior and subsequent RVUs and benefit from the higher limit on subsequent

RVUs.

Applications that use a fixed select( ) limit run on both prior and subsequent RVUs if compiled on prior RVUs but only run on subsequent RVUs if compiled on a subsequent RVU.

Applications that mix select( )-related object modules from prior and subsequent RVUs are unsafe because the select( ) file descriptor bit arrays have different size declarations in the RVUs.

To avoid application failures, select( )-related object modules should be compiled using a consistent set of select( ) definitions.

527186-003 Hewlett-Packard Company 7

7

select(2) OSS System Calls Reference Manual

Specifying arbitrarily large values for the nfds parameter can cause the function to behave inefficiently.

The time limit value specified by the timeout parameter has no effect on the operation of the

alarm( ) or settimer( ) function.

RETURN VALUES

Upon successful completion, the select( ) function returns the number of ready objects represented by corresponding file descriptor bits in all the file descriptor sets. When an error occurs, the value -1 is returned, and errno is set to indicate the error.

When the time limit specified by the timeout parameter expires, the select( ) function returns the value 0 (zero), and all bits in the objects pointed to by the readfds, writefds, and errorfds parameters are also set to 0 (zero).

When select( ) returns an error, the file descriptor sets pointed to by the readfds, writefds, and

errorfds parameters remain unmodified.

The FD_CLR, FD_SET, and FD_ZERO macros do not return values. The FD_ISSET macro returns a nonzero value when the bit for the file descriptor specified by its fd parameter is set in the file descriptor set pointed to by its fdset parameter; otherwise, the FD_ISSET macro returns 0

(zero).

ERRORS

If any of these conditions occurs, the select( ) function sets errno to the corresponding value:

[EBADF]

[EINTR]

[EINVAL]

One of the specified file descriptor sets is invalid. One of these conditions occurred:

The invalid file descriptor set contains a file descriptor for a file that is not open.

The invalid file descriptor set contains a file descriptor that identifies an

AF_INET AF_INET6 socket, but the current processor is not running a transport agent process to support the socket. The file descriptor can only be closed.

A signal was delivered before the time limit specified by the timeout parameter expired and before any of the selected events occurred.

One of these conditions occurred:

The value specified for the nfds parameter is less than 0 (zero) or greater than FD_SETSIZE.

The time limit specified by the timeout parameter is invalid. One of its components is negative or too large.

[ENETDOWN]

One of the specified file descriptors specifies a file on a remote HP NonStop node, but communication with the remote node has been lost.

[ENOTSUP] One of the specified file descriptors refers to a terminal device file that does not support nonblocking input/output and the descriptor was opened in

O_NONBLOCK mode. The HP implementation does not support this use of the

select( ) function.

For all other error conditions, errno is set to the appropriate Guardian file-system error number.

See the Guardian Procedure Errors and Messages Manual for more information about a specific

Guardian file-system error.

7

8 Hewlett-Packard Company 527186-003

System Functions (s and S) select(2)

RELATED INFORMATION

Functions: fcntl(2), read(2), write(2).

STANDARDS CONFORMANCE

The HP implementation does not support use of this function on terminal device files.

HP extensions to the XPG4 Version 2 specification are:

The errno value [ENOTSUP] can be returned for a call that attempts to select a terminal device file.

The errno value [ENETDOWN] can be returned.

The time interval specified by the timeout parameter must meet these criteria:

— The maximum interval is 2**31 seconds plus 2**31 microseconds. If a value greater than this is specified, the maximum is used instead.

— If a specified interval is not a whole multiple of 10 milliseconds, the next highest whole multiple is used instead.

527186-003 Hewlett-Packard Company 7

9

semctl(2) OSS System Calls Reference Manual

NAME

semctl - Performs semaphore control operations

LIBRARY

G-series native OSS processes: /G/system/sysnn/zossksrl

H-series OSS processes: /G/system/zdllnnn/zosskdll

SYNOPSIS

#include <sys/sem.h> int semctl(

int semid,

int semnum,

int cmd [,

. . . ]);

In this instance, the elipsis ( . . . ) indicates that the function is extensible. An additional, optional parameter can be specified.

PARAMETERS

semid

Specifies the ID of the semaphore set.

semnum cmd

Specifies the number of the semaphore to be processed.

Specifies the type of operation (see DESCRIPTION).

the fourth parameter

Is defined in the XPG4 specification in a manner that avoids conflict with the

ISO C standard.

This parameter is required when the cmd parameter has values of GETALL,

IPC_SET, IPC_STAT, SETALL, and SETVAL. The fourth parameter can be omitted in all other calls.

This parameter must be defined in a user program as follows:

union semun { int struct semid_ds unsigned short

} arg;

val;

*buf;

*array;

The fields have the following definitions:

val

*buf

Contains the semaphore value to which the semval field of the

sem structure is set when the cmd parameter has the value SET-

VAL. Individual semaphores are defined using the sem structure, where semval is one of the structure’s fields.

Points to a semid_ds structure. When the IPC_STAT value is specified for the cmd parameter, semctl( ) copies the contents of the requested semid_ds structure into the location pointed to by the *buf parameter.

When the IPC_SET value is specified for the cmd parameter,

semctl( ) copies the contents of the location pointed to by the

*buf parameter into the semid_ds structure associated with the semaphore specified by the semnum parameter.

7

10 Hewlett-Packard Company 527186-003

System Functions (s and S) semctl(2)

*array

arg

Points to an array of semaphore values. These values are returned when the cmd parameter has the value GETALL.

These values are used to set semaphore values when the cmd parameter has the value SETALL.

Specifies the instance of the union used for the fourth parameter.

DESCRIPTION

An OSS semaphore is identified by a set ID and by a unique semaphore number within that set

ID. The semaphore set ID is unique within an HP NonStop server node.

The semctl( ) function allows a process to perform various operations on the following:

An individual semaphore within a semaphore set

All semaphores within a semaphore set

The semid_ds structure associated with the semaphore set

The semctl( ) function also allows a process to remove the semaphore set ID and its associated

semid_ds structure. Individual semaphores are defined using the sem structure.

The cmd parameter determines which operation is performed. The following values for cmd operate on the specified semaphore (given by the semnum parameter) within the specified semaphore set (given by the semid parameter):

GETNCNT

Returns the number of processes waiting for the specified semaphore’s value to become greater than its current value. This number is returned as the value of the semncnt field from the semid_ds structure.

This operation requires read access permission.

GETPID

GETVAL

Returns the OSS process ID of the process that last operated on the specified semaphore. This operation requires read access permission.

Returns the value of the specified semaphore. This operation requires read access permission.

GETZCNT

Returns the number of processes waiting for the specified semaphore’s value to become 0 (zero). This number is returned as the value of the semzcnt field from | the semid_ds structure.

|

This operation requires read access permission.

SETVAL

Sets the value of the specified semaphore to the value specified through the fourth parameter (arg.val). When this operation successfully executes, the system clears the semaphore’s adjust-on-exit value in all processes that have a

semadj value for this semaphore. It also wakes up all processes that are waiting | on this semaphore when the value of semzcnt or semncnt is greater than zero, depending on whether the value of this semaphore is set to zero or a positive integer respectively.

|

|

|

This operation requires alter access permission.

|

|

The following values for cmd operate on all the semaphores in the specified semaphore set:

GETALL

Returns the values of all semaphores in the set by placing these values in the array pointed to in fourth parameter (arg.array). This operation requires read access permission.

527186-003 Hewlett-Packard Company 7

11

semctl(2) OSS System Calls Reference Manual

SETALL

Sets the respective values of all semaphores in the set to the values specified in the array pointed to in the fourth parameter (arg.array). When this operation successfully executes, the system clears the semaphore’s adjust-on-exit value in all processes that have a semadj value for this semaphore. It also wakes up all | processes that are waiting on a semaphore when the value of semzcnt or

semncnt is greater than zero, depending on whether the respective value of a specific semaphore is set to zero or a positive integer respectively.

|

|

|

This operation requires alter access permission.

The following interprocess communications (IPC) commands can also be used as values for cmd:

IPC_RMID

Removes the semaphore set ID and destroys the set of semaphores and the

semid_ds structure associated with it.

This is a restricted operation. The effective user ID of the calling process must be either the super ID or equal to the value of the sem_perm.cuid or

sem_perm.uid field in the associated semid_ds structure.

IPC_SET

Sets the semaphore set by copying selected user-supplied values in the structure pointed to in the fourth parameter (arg.buf) into corresponding fields in the

semid_ds structure associated with the semaphore set ID.

This is a restricted operation. The calling process must either have appropriate privileges, be the process that created the semaphore set, or be the process that currently owns the semaphore set.

The fields are set as follows:

The sem_perm.uid field is set as specified in the uid field of the

semid_ds ipc_perm structure pointed to in the fourth parameter

(arg.buf).

The sem_perm.gid field is set as specified in the gid field of the

semid_ds ipc_perm structure pointed to in the fourth parameter

(arg.buf).

The sem_perm.mode field is set to the access modes for the semaphore set. Only the low-order nine bits are set.

The sem_ctime field is updated.

IPC_STAT

Queries the semaphore set ID by copying the contents of its associated semid_ds structure into the structure pointed to in the fourth parameter (arg.buf). This operation requires read access permission.

Use From the Guardian Environment

If called from a Guardian process, the actions of this function are undefined and errno is set to

[ENOTOSS].

RETURN VALUES

Upon successful completion, the value returned depends on the value of the cmd parameter as follows:

GETNCNT

Returns the value of the semncnt field from the semid_ds structure.

7

12 Hewlett-Packard Company 527186-003

System Functions (s and S) semctl(2)

GETPID

Returns the value of the sempid field from the semid_ds structure.

GETVAL

Returns the value of the semval field from the semid_ds structure.

GETZCNT

Returns the value of the semzcnt field from the semid_ds structure.

Upon successful completion, all other values of cmd return the value 0 (zero).

If the semctl( ) function fails, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the semctl( ) function sets errno to the corresponding value:

[EACCES]

[EFAULT]

The calling process does not have the required read or alter access.

One of the following is true:

The cmd parameter is IPC_STAT, and either the structure pointed to in the fourth parameter (arg.buf) is not in the address space of the process or the function cannot write into the structure pointed to in the fourth parameter.

The cmd parameter is GETALL, and either the structure pointed to in the fourth parameter (arg.buf) is not in the address space of the process or the function cannot write into the structure pointed to in the fourth parameter.

[EINVAL] One of the following conditions is true:

The semid parameter is not a valid semaphore set ID.

The value of the semnum parameter is less than 0 (zero), or it is greater than or equal to the value of the sem_nsems field in the semid_ds structure.

The cmd parameter is not a valid operation.

[ENOTOSS] The calling process is not an OSS process. The requested operation is not supported from the Guardian environment.

[EPERM] All of the following conditions are true:

The cmd parameter is equal to IPC_RMID or IPC_SET.

The effective user ID of the calling process does not have appropriate privileges.

The effective user ID of the calling process is not equal to the value of the sem_perm.cuid or sem_perm.uid field in the semid_ds structure associated with the semaphore set ID.

[ERANGE] The cmd parameter is SETALL or SETVAL, and the semaphore value in the

semval field of the semid_ds structure associated with the semaphore set ID is greater than the system-defined maximum.

527186-003 Hewlett-Packard Company 7

13

semctl(2) OSS System Calls Reference Manual

RELATED INFORMATION

Commands: ipcrm(1), ipcs(1).

Functions: ftok(3), semget(2), semop(2).

STANDARDS CONFORMANCE

The following are HP extensions to the XPG4 Version 2 specification:

The errno values [EFAULT] and [ENOTOSS] can be returned.

7

14 Hewlett-Packard Company 527186-003

System Functions (s and S) semget(2)

NAME

semget - Creates a new semaphore set ID or returns the ID of an existing semaphore set

LIBRARY

G-series native OSS processes: /G/system/sysnn/zossksrl

H-series OSS processes: /G/system/zdllnnn/zosskdll

SYNOPSIS

#include <sys/sem.h> int semget(

key_t key,

int nsems,

int semflg);

PARAMETERS

key nsems semflg

Specifies the key that identifies the semaphore set. The IPC_PRIVATE key can be used to ensure the return of a new (unused) semaphore set ID in the semaphore set table.

Specifies the number of OSS semaphores to create in the semaphore set.

Specifies the creation flags. Possible values are as follows:

IPC_CREAT

If the key does not exist, the semget( ) function creates a semaphore set ID using the given key.

IPC_CREAT | IPC_EXCL

If the key already exists, the semget( ) function fails and returns an error notification.

DESCRIPTION

The semget( ) function returns the semaphore set ID for the semaphore set identified by the key parameter. If the key parameter already has a semaphore set ID associated with it and (semflg &

IPC_CREAT) is 0 (zero), that ID is returned.

A new semaphore set ID, the associated semaphore set table, and a new semaphore set of nsems

OSS semaphores are created when either of the following is true:

The value of IPC_PRIVATE is used for the key parameter.

The key parameter does not already have a semaphore set ID associated with it, and

(semflg & IPC_CREAT) is not 0 (zero).

After creating a new semaphore set ID, the semget( ) function initializes the semid_ds structure associated with the ID as follows:

The sem_perm.cuid and sem_perm.uid fields are set equal to the effective user ID of the calling process.

The sem_perm.cgid and sem_perm.gid fields are set equal to the effective group ID of the calling process.

The low-order nine bits of the sem_perm.mode field are set equal to the low-order nine bits of the semflg parameter.

527186-003 Hewlett-Packard Company 7

15

semget(2) OSS System Calls Reference Manual

The sem_nsems field is set to the value of the nsems parameter.

The sem_otime field is set to 0 (zero), and the sem_ctime field is set equal to the current time.

The semget( ) function does not initialize the sem structure associated with each semaphore in the set. The individual OSS semaphores are initialized by using the semctl( ) function with the

SETVAL or SETALL value for the cmd parameter.

Key Creation

The key represents a user-designated name for a given semaphore set. Keys are usually selected by calling the ftok( ) function before calling the semget( ) function. The ftok( ) function returns a key based on a path and an interprocess communications identifier. This key is then passed to the semget( ) function, which returns a semaphore set ID. The semaphore set ID is then used in calls to the semop( ) and semctl( ) functions.

Propagation During Process Creation

Semaphore set IDs attached to a parent process are also attached to a child process. A semaphore set cannot be shared when a child process is created in a different processor than that used by the parent. If a process attempts to create a child process in a different processor while the parent process has any adjust-on-exit (semadj) value, the process creation fails and errno is set to [EHLDSEM].

Cleaning Up Semaphores

An OSS semaphore remains allocated until it is removed. Normally, the semctl( ) function is used with the IPC_RMID value of the cmd parameter to remove unneeded OSS semaphores.

The HP implementation of OSS environment semaphores does not provide facilities to detect or avoid deadlocks.

An allocated OSS semaphore set ID is not removed automatically when the last process using it terminates. Instead, the OSS semaphore set ID becomes inactive. The user must remove inactive

OSS semaphore set IDs to avoid wasting system resources.

The status of OSS semaphore set IDs can be checked with the ipcs command. Inactive OSS semaphore set IDs can be removed with the ipcrm command.

Semaphore Use Between Environments

OSS and Guardian environment nonprivileged binary semaphores coexist but do not interoperate.

Guardian environment processes cannot use OSS environment function calls for access to OSS semaphores. OSS environment processes can create and operate on nonprivileged binary semaphores through Guardian environment procedure calls.

Use From the Guardian Environment

If called from a Guardian process, the actions of this function are undefined and errno is set to

[ENOTOSS].

RETURN VALUES

Upon successful completion, a nonnegative semaphore set ID is returned. Otherwise, the

semget( ) function returns the value -1 and sets errno to indicate the condition.

ERRORS

If any of the following conditions occurs, the semget( ) function sets errno to the corresponding value:

[EACCES] A semaphore set ID already exists for the key parameter, but operation permission as specified by the low-order nine bits of the semflg parameter was not granted.

7

16 Hewlett-Packard Company 527186-003

System Functions (s and S) semget(2)

[EEXIST]

[EINVAL]

A semaphore set ID already exists for the key parameter, but ((semflg &

IPC_CREAT) && (semflg & IPC_EXCL)) is not equal to 0 (zero).

One of the following conditions is true:

A semaphore set ID already exists for the key parameter, but the number of semaphores in the set is less than nsems and nsems is not equal to 0

(zero).

A semaphore set ID does not already exist, but the value of the nsems parameter is either less than or equal to 0 (zero) or greater than the system-defined limit.

[ENOENT] A semaphore set ID does not exist for the key parameter, and (semflg &

IPC_CREAT) is equal to 0 (zero).

[ENOSPC] An attempt to create a new semaphore set ID exceeded the processor limit on the number of allowed semaphores.

[ENOTOSS] The calling process is not an OSS process. The requested operation is not supported from the Guardian environment.

RELATED INFORMATION

Commands: ipcrm(1), ipcs(1).

Functions: exec(2), _exit(2), fork(2), ftok(3), semctl(2), semop(2), tdm_execve(2),

tdm_execvep(2), tdm_fork(2), tdm_spawn(2), tdm_spawnp(2).

STANDARDS CONFORMANCE

The following are HP extensions to the XPG4 Version 2 specification:

The errno value [ENOTOSS] can be returned.

527186-003 Hewlett-Packard Company 7

17

semop(2) OSS System Calls Reference Manual

NAME

semop - Performs semaphore operations

LIBRARY

G-series native OSS processes: /G/system/sysnn/zossksrl

H-series OSS processes: /G/system/zdllnnn/zosskdll

SYNOPSIS

#include <sys/sem.h> int semop(

int semid,

struct sembuf *sops,

size_t nsops);

PARAMETERS

semid sops nsops

Specifies the ID of the semaphore set.

Points to the user-defined array of sembuf structures that contain the semaphore operations.

Specifies the number of sembuf structures in the array.

DESCRIPTION

The semop( ) function atomically performs a set of operations on the semaphores specified by the

sem_num fields in the structures pointed to by the sops parameter and by the semaphore set ID specified as the semid parameter.

If a process cannot execute a specified operation on a single semaphore within the specified semaphore set, it cannot execute any operation on any semaphore within that set. Values related to any semaphores in the set remain unchanged by the failed call to the semop( ) function. (The calling process’s adjust-on-exit value, semadj, for the semaphore is also unaffected by a failed call. Refer to the exit(3) reference page for more information about semadj use.)

All processes waiting (suspended) for a semaphore are awakened when an operation occurs that could cause any one of them to proceed.

The semaphore operations are defined in the array pointed to by the sops parameter. The sops array contains nsops elements, each of which is represented by a sembuf structure.

The sembuf structure (from the sys/sem.h header file) is defined as follows:

struct sembuf { unsigned short int sem_num; short int short int sem_op; sem_flg;

};

The fields in the sembuf structure are defined as follows:

sem_num sem_op

Specifies an individual semaphore within the semaphore set.

Specifies the operation to perform on the semaphore. The sem_op operation is specified as a negative integer, a positive integer, or 0 (zero). The effects of these operations are described later in this reference page.

7

18 Hewlett-Packard Company 527186-003

System Functions (s and S) semop(2) sem_flg

Specifies various flags for the operations. The possible values are as follows:

SEM_UNDO

Instructs the system to adjust the process’s adjust-on-exit value

(semadj) for a modified semaphore. When the process exits, the system uses this value to restore the semaphore to the value it had before any modifications by the process. This flag is used to prevent locking of resources allocated through a semaphore by a process that no longer exists.

IPC_NOWAIT

Instructs the system to return an error condition if a requested operation would cause the process to sleep. If the system returns an error condition, none of the requested semaphore operations are performed.

If the sem_op field of the sembuf structure contains a negative integer and the calling process has alter access permission, the semop( ) function does one of the following:

If the semaphore’s current value (in the semval field of the sem structure) is equal to or greater than the absolute value of sem_op, the absolute value of sem_op is subtracted from semval. If (sem_flg & SEM_UNDO) is not zero, the absolute value of sem_op is added to the calling process’s semadj value for the semaphore.

If the semaphore’s current value (in the semval field of the sem structure) is less than the absolute value of sem_op and (sem_flg & IPC_NOWAIT) is not zero, semop( ) returns immediately with an error.

If the semaphore’s current value (in the semval field of the sem structure) is less than the absolute value of sem_op and (sem_flg & IPC_NOWAIT) is 0 (zero), semop( ) increments the semaphore’s semncnt value (in the sem structure) and suspends the calling process. If the process is suspended, it sleeps until one of the following occurs:

— The semval value becomes equal to or greater than the absolute value of

sem_op. When this happens, the semaphore’s semncnt value is decremented, the absolute value of sem_op is subtracted from semval, and, if (sem_flg &

SEM_UNDO) is not zero, the absolute value of sem_op is added to the calling process’s semadj value for the semaphore.

— The semaphore set ID specified by the semid parameter is removed from the system. When this happens, semop( ) returns immediately with an error.

— The calling process catches a signal. When this happens, the semaphore’s

semncnt value is decremented and the calling process resumes execution as directed by the sigaction( ) function.

If the sem_op field of the sembuf structure contains a positive integer and the calling process has alter access permission, semop( ) adds the sem_op value to the semaphore’s current semval value (in the sem structure). If (sem_flg & SEM_UNDO) is not zero, the sem_op value is subtracted from the calling process’s semadj value for the semaphore.

527186-003 Hewlett-Packard Company 7

19

semop(2) OSS System Calls Reference Manual

If the sem_op field of the sembuf structure contains 0 (zero) and the calling process has read access permission, semop( ) does one of the following:

If the semval field of the sem structure contains 0 (zero), semop( ) returns immediately.

If semval is not zero and (sem_flg & IPC_NOWAIT) is not zero, semop( ) returns immediately.

If semval is not zero and (sem_flg & IPC_NOWAIT) is 0 (zero), semop( ) increments the semaphore’s semzcnt value (in the sem structure) and suspends the calling process.

If the process is suspended, it sleeps until one of the following occurs:

— The semval value becomes 0 (zero). When this happens, the semaphore’s

semzcnt value (in the sem structure) is decremented.

— The semaphore set ID specified by the semid parameter is removed from the system. When this happens, semop( ) returns immediately with an error.

— The calling process catches a signal. When this happens, the semaphore’s

semzcnt value is decremented and the calling process resumes execution as directed by the sigaction( ) function.

The value of the sempid field in the sem structure for each OSS semaphore that is operated upon is set to the OSS process ID of the calling process.

Use From the Guardian Environment

If called from a Guardian process, the actions of this function are undefined and errno is set to

[ENOTOSS].

RETURN VALUES

Upon successful completion, the semop( ) function returns the value 0 (zero).

If the semop( ) function fails, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the semop( ) function sets errno to the corresponding value:

[E2BIG]

[EACCES]

[EAGAIN]

[EFAULT]

[EFBIG]

[EIDRM]

[EINTR]

The value of the nsops parameter is greater than the system-defined maximum.

The calling process does not have the required access permission.

The value of (sem_flg && IPC_NOWAIT) is TRUE, but the requested operation would cause the calling process to be suspended.

The address used for the sops parameter is invalid.

The sem_num field of the sembuf structure is less than 0 (zero) or greater than or equal to the number of semaphores in the set identified by the semid parameter.

The semaphore set ID specified by the semid parameter was removed from the system while the process was waiting for it.

The semop( ) function was interrupted by a signal.

7

20 Hewlett-Packard Company 527186-003

System Functions (s and S) semop(2)

[EINVAL] One of the following conditions is true:

The semid parameter is not a valid semaphore set ID.

The number of semaphores for which the SEM_UNDO flag is specified exceeds the system-defined limit.

[ENOSPC] One of the following conditions is true:

The system-defined limit on the number of undo entries for an undo structure would be exceeded.

The system-defined limit on the number of SEM_UNDO structures for a single processor would be exceeded.

The number of semadj values for the processor would exceed the system limit.

[ENOTOSS] The calling process is not an OSS process. The requested operation is not supported from the Guardian environment.

[ERANGE] On of the following conditions exists:

An operation caused a semval value in a sem structure to overflow the system-defined limit.

An operation caused an adjust-on-exit (semadj) value to exceed the system-defined limit.

RELATED INFORMATION

Functions: exec(2), _exit(2), fork(2), semctl(2), semget(2), sigaction(2), tdm_execve(2),

tdm_execvep(2), tdm_fork(2), tdm_spawn(2), tdm_spawnp(2).

STANDARDS CONFORMANCE

The following are HP extensions to the XPG4 Version 2 specification:

The errno values [EFAULT] and [ENOTOSS] can be returned.

527186-003 Hewlett-Packard Company 7

21

send(2) OSS System Calls Reference Manual

NAME

send - Sends a message on a connected socket

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/socket.h> ssize_t send(

int socket,

const void *buffer,

size_t length,

int flags

);

PARAMETERS

socket buffer length flags

Specifies the file descriptor of the socket.

Points to the buffer containing the message to send.

Specifies the length in bytes of the message to send.

Is a value that controls message transmission. The value of the flags parameter is formed by bitwise ORing zero or more of the following values:

MSG_DONTROUTE

Sends without using routing tables. (Not recommended, use for debugging purposes only.)

MSG_OOB

Sends out-of-band data on sockets that support out-of-band communications.

DESCRIPTION

The send( ) function begins transmission of a message to a peer socket. The send( ) function sends a message only when the socket is connected.

The length of the message to be sent is specified by the length parameter. If the message is too long to pass through the underlying protocol, the send( ) function fails and does not transmit the message.

Successful completion of a call to send( ) does not imply successful delivery of the message. A return value of -1 indicates only locally detected errors.

If the sending socket has no space to hold the message to be transmitted and the socket’s file descriptor is blocking (O_NONBLOCK is not set), the send( ) function blocks until space is available. If the sending socket has no space to hold the message to be transmitted and the socket’s file descriptor is marked nonblocking (O_NONBLOCK is set), the send( ) function fails and sets errno to [EWOULDBLOCK].

NOTES

When data can be sent, a call to the select( ) function indicates that the file descriptor for the socket is ready for writing.

Calling the send( ) function with a flags parameter of 0 (zero) is identical to calling the write( ) function.

7

22 Hewlett-Packard Company 527186-003

System Functions (s and S) send(2)

RETURN VALUES

Upon successful completion, the send( ) function returns the number of bytes sent. Otherwise, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the send( ) function sets errno to the corresponding value:

[EBADF] The socket parameter is not a valid file descriptor.

[ECONNRESET]

One of the following conditions occurred:

The transport-provider process for this socket is no longer available.

The TCP/IP subsystem for this socket is no longer available.

The connection was forcibly closed by the peer socket.

The socket can only be closed.

[EDESTADDRREQ]

The socket is not connection-oriented and no peer address is set.

[EFAULT] A user-supplied memory buffer cannot be accessed.

[EINTR]

[EIO]

A signal interrupted the function before any data was transmitted.

An input or output error occurred.

[EMSGSIZE] The message is too large to be sent all at once, as required by the socket.

[ENETDOWN]

The local interface used to reach the destination is down.

[ENETUNREACH]

No route to the network or host is present.

[ENOBUFS] There was not enough buffer space available to complete the call. A retry at a later time might succeed.

[ENOMEM] Required memory resources were not available. A retry at a later time might succeed.

[ENOTCONN] The socket either is not connected or has not had the peer socket previously specified.

[ENOTSOCK] The socket parameter does not refer to a socket.

[EOPNOTSUPP]

The specified value for the flags parameter is not supported for this socket type or protocol.

[EPIPE] One of the following conditions occurred:

An attempt was made to send a message on a socket that is shut down for writing.

An attempt was made to send a message on a connection-oriented socket and the peer socket is closed or shut down for reading. The SIGPIPE signal is also sent to the calling process.

527186-003 Hewlett-Packard Company 7

23

send(2) OSS System Calls Reference Manual

[EWOULDBLOCK]

The socket’s file descriptor is marked nonblocking (O_NONBLOCK is set) and the operation would block.

RELATED INFORMATION

Functions: connect(2), getsockopt(2), recv(2), recvfrom(2), recvmsg(2), select(2),

sendmsg(2), sendto(2), setsockopt(2), shutdown(2), socket(2).

STANDARDS CONFORMANCE

The HP implementation does not return the errno value [ENOSR].

The following are HP extensions to the XPG4 specification:

The errno value [ECONNRESET] can be returned when the transport-provider process is not available.

7

24 Hewlett-Packard Company 527186-003

System Functions (s and S) sendmsg(2)

NAME

sendmsg - Sends a message on a socket using a message structure

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/socket.h> ssize_t sendmsg(

int socket,

const struct msghdr *message,

int flags

);

PARAMETERS

socket message

Specifies the file descriptor of the socket.

Points to a msghdr structure containing both the destination address for the outgoing message and the buffers for the outgoing message. The length and format of the address depend on the address family for the socket. The msg_flags member of the structure is ignored. For:

AF_INET sockets

A pointer in msghdr to the address structure sockaddr_in must be cast as a struct sockaddr.

AF_INET6 sockets

A pointer to the address structure sockaddr_in6 must be cast as a struct sockaddr.

AF_UNIX sockets

A pointer to the address structure sockaddr_un must be cast as a

struct sockaddr.

flags

Is a value that controls message transmission. The value of the flags parameter is formed by bitwise ORing zero or more of these values:

MSG_DONTROUTE

Sends without using routing tables. (Not recommended; use only for debugging purposes.)

MSG_OOB

Sends out-of-band data on sockets that support out-of-band communications.

DESCRIPTION

The sendmsg( ) function sends a message through a connection-oriented or connectionless socket. If the socket is connectionless, the message is sent to the address specified in the

msghdr structure. If the socket is connection-oriented, the destination address in the msghdr structure is ignored.

Successful completion of a call to sendmsg( ) does not imply successful delivery of the message.

A return value of -1 indicates only locally detected errors.

If the sending socket has no space to hold the message to be transmitted and the socket’s file descriptor is blocking (O_NONBLOCK is not set), the sendmsg( ) function blocks until space is available. If the sending socket has no space to hold the message to be transmitted and the socket’s file descriptor is marked nonblocking (O_NONBLOCK is set), the sendmsg( ) function

527186-003 Hewlett-Packard Company 7

25

sendmsg(2) OSS System Calls Reference Manual

fails and sets errno to [EWOULDBLOCK].

In the msghdr structure, the msg_control and msg_controllen members specify the ancillary data buffer that can be used only by sockets in the AF_UNIX domain to pass file descriptors to another process on the same node. The msg_control member can be a null pointer if ancillary data is not desired or required. If the msg_control member is nonnull, it points to an ancillary data buffer consisting of a cmsghdr structure followed by one to sixteen file descriptors. The

msg_controllen member specifies the size of the ancillary data buffer.

If sendmsg( ) is called with an ancillary data buffer, the members of the cmsghdr structure must be set as follows:

The cmsg_level member must be set to SOL_SOCKET.

The cmsg_type member must be set to SCM_RIGHTS.

The value of the cmsg_len member must be equal to the value of the msg_controllen member of the msghdr structure.

NOTES

When data can be sent, a call to the select( ) function indicates that the file descriptor for the socket is ready for writing.

RETURN VALUES

Upon successful completion, the sendmsg( ) function returns the number of normal bytes sent.

Ancillary data, if present, is not counted in the total number of bytes sent.

If the sendmsg( ) function call fails, the value -1 is returned, and errno is set to indicate the error.

ERRORS

If any of these conditions occurs, the sendmsg( ) function sets errno to the corresponding value:

[EACCES] The socket is in the AF_UNIX domain and either search permission is denied for a component of the pathname in the msghdr structure or write access to the specified socket is denied.

[EAFNOSUPPORT]

Addresses in the specified address family cannot be used with this socket.

[EBADF] One of these conditions exists:

The socket parameter is not a valid file descriptor.

The socket is in the AF_UNIX domain, and one or more of the file descriptors being passed is invalid.

[ECONNRESET]

One of these conditions occurred:

The transport-provider process for this socket is no longer available.

The TCP/IP subsystem for this socket is no longer available.

The connection was forcibly closed by the peer socket.

The socket can only be closed.

7

26 Hewlett-Packard Company 527186-003

System Functions (s and S) sendmsg(2)

[EDESTADDRREQ]

The socket is not connection-oriented, no peer address is set, and no destination address is specified.

[EFAULT]

[EINTR]

[EINVAL]

A user-supplied memory buffer cannot be accessed.

A signal interrupted the function before any data was transmitted.

One of these conditions occurred:

The socket is in the AF_UNIX domain, and the msg_control member contains either more than 16 file descriptors or fewer than 1 file descriptor.

The socket is in the AF_UNIX domain, and an attempt was made to send more than one cmsghdr structure.

The socket is in the AF_UNIX domain, and the value of the cmsg_len member is not equal to the value of the msg_controllen member.

The socket is in the AF_UNIX domain, and the cmsg_type member is not equal to SCM_RIGHTS.

The sum of the values specified for the msg_iovlen member of the

msghdr structure is too large for a data item of type ssize_t.

[EIO]

[ELOOP]

The socket is in the AF_UNIX domain, and the transport agent failed to inherit the file descriptors being passed, or an input or output error occurred.

The socket is in the AF_UNIX domain, and too many symbolic links were encountered in translating the pathname specified by the msghdr structure.

[EMSGSIZE] The message is too large to be sent all at once, as required by the socket.

[ENAMETOOLONG]

The socket is in the AF_UNIX domain, and one of these conditions exists:

The pathname in the msghdr structure exceeds PATH_MAX characters.

A component of the pathname in the msghdr structure exceeds

NAME_MAX characters.

The intermediate result of pathname resolution when a symbolic link is part of the pathname in the msghdr structure exceeds PATH_MAX characters.

The pathconf( ) function can be called to obtain the applicable limits.

[ENOBUFS] Not enough buffer space was available to complete the call. A retry at a later time might succeed.

[ENOENT] The socket is in the AF_UNIX domain, and one of these conditions occurred:

A component of the pathname in the msghdr structure does not name an existing file.

The msghdr structure specifies an empty string as a pathname.

527186-003 Hewlett-Packard Company 7

27

sendmsg(2) OSS System Calls Reference Manual

[ENOMEM] Required memory resources were not available. A retry at a later time might succeed.

[ENOPROTOOPT]

The socket is in the AF_UNIX domain, and the cmsg_level member is not equal to SOL_SOCKET.

[ENOTCONN] The socket is connection-oriented but is not connected.

[ENOTDIR] The socket is in the AF_UNIX domain, and the pathname specified by the

msghdr structure contains a component that is not a directory.

[ENOTSOCK] The socket parameter does not refer to a socket.

[EOPNOTSUPP]

The specified value for the flags parameter is not supported for this socket type or protocol.

[EPIPE] One of these conditions occurred:

An attempt was made to send a message on a socket that is shut down for writing.

An attempt was made to send a message on a connection-oriented socket, and the peer socket is closed or shut down for reading. The SIG-

PIPE signal is also sent to the calling process.

[EWOULDBLOCK]

The socket file descriptor is marked nonblocking (O_NONBLOCK is set), and the operation would block.

RELATED INFORMATION

Functions: getsockopt(2), recv(2), recvfrom(2), recvmsg(2), select(2), send(2), sendto(2), set-

sockopt(2), shutdown(2), socket(2), socketpair(2).

STANDARDS CONFORMANCE

The HP implementation does not return the errno value [ENOSR].

HP extensions to the XPG4 specification are:

The errno value [ECONNRESET] can be returned when the transport-provider process is not available.

The errno value [ENOPROTOOPT] can be returned.

7

28 Hewlett-Packard Company 527186-003

System Functions (s and S) sendto(2)

NAME

sendto - Sends a message on a socket

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/socket.h> ssize_t sendto(

int socket,

const void *message,

size_t length,

int flags,

const struct sockaddr *dest_addr,

size_t dest_len

);

PARAMETERS

socket message length flags dest_addr

Specifies the file descriptor of the socket.

Points to the buffer containing the message to be sent.

Specifies the length in bytes of the message to be sent.

Is a value that controls message transmission. The value of the flags parameter is formed by bitwise ORing zero or more of the following values:

MSG_DONTROUTE

Sends without using routing tables. (Not recommended; use for debugging purposes only.)

MSG_OOB

Sends out-of-band data on sockets that support out-of-band communications.

Points to a sockaddr structure that contains the destination address. The length and format of the address depends on the address family of the socket. For:

dest_len

AF_INET sockets

A pointer to the address structure sockaddr_in must be cast as a

struct sockaddr.

AF_INET6 sockets

A pointer to the address structure sockaddr_in6 must be cast as a struct sockaddr.

AF_UNIX sockets

A pointer to the address structure sockaddr_un must be cast as a

struct sockaddr.

Specifies the length of the sockaddr structure pointed to by the dest_addr parameter.

527186-003 Hewlett-Packard Company 7

29

sendto(2) OSS System Calls Reference Manual

DESCRIPTION

The sendto( ) function sends a message through a connection-oriented or connectionless socket.

If the socket is connectionless, the message is sent to the address specified in the sockaddr structure pointed to by the dest_addr parameter. If the socket is connection-oriented, the dest_addr parameter is ignored.

Successful completion of a call to sendto( ) does not imply successful delivery of the message. A return value of -1 indicates only locally detected errors.

If the sending socket has no space to hold the message to be transmitted and the socket’s file descriptor is blocking (O_NONBLOCK is not set), the sendto( ) function blocks until space is available. If the sending socket has no space to hold the message to be transmitted and the socket’s file descriptor is marked nonblocking (O_NONBLOCK is set), the sendto( ) function fails and sets errno to [EWOULDBLOCK].

NOTES

When data can be sent, a call to the select( ) function indicates that the file descriptor for the socket is ready for writing.

RETURN VALUES

Upon successful completion, the sendto( ) function returns the number of bytes sent. Otherwise, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the sendto( ) function sets errno to the corresponding value:

[EACCES] The socket is in the AF_UNIX domain and either search permission is denied for a component of the pathname in the sockaddr structure, or write access to the specified socket is denied.

[EAFNOSUPPORT]

Addresses in the specified address family cannot be used with this socket.

[EBADF] The socket parameter is not a valid file descriptor.

[ECONNRESET]

One of the following conditions occurred:

The transport-provider process for this socket is no longer available.

The TCP/IP subsystem for this socket is no longer available.

The connection was forcibly closed by the peer socket.

The socket can only be closed.

[EDESTADDRREQ]

The socket is not connection-oriented and does not have its peer address set, and no destination address was specified.

[EFAULT] A user-supplied memory buffer cannot be accessed.

[EHOSTUNREACH]

The destination host cannot be reached.

7

30 Hewlett-Packard Company 527186-003

System Functions (s and S) sendto(2)

[EINTR]

[EIO]

[EINVAL]

A signal interrupted the function before any data was transmitted.

The socket is in the AF_UNIX domain and an input or output error occurred.

The dest_len parameter is not a valid length for the address family.

[ELOOP] The socket is in the AF_UNIX domain and too many symbolic links were encountered in translating the pathname in the sockaddr structure.

[EMSGSIZE] The message is too large to be sent all at once, as required by the socket.

[ENAMETOOLONG]

The socket is in the AF_UNIX domain and one of the following conditions exists:

The pathname in the sockaddr structure exceeds PATH_MAX characters.

A component of the pathname in the sockaddr structure exceeds

NAME_MAX characters.

The intermediate result of pathname resolution when a symbolic link is part of the pathname in the sockaddr structure exceeds PATH_MAX characters.

The pathconf( ) function can be called to obtain the applicable limits.

[ENETDOWN]

The local interface used to reach the destination is down.

[ENETUNREACH]

No route to the network or host is present.

[ENOBUFS] There was not enough buffer space available to complete the call. A retry at a later time might succeed.

[ENOENT] The socket is in the AF_UNIX domain and one of the following conditions exists:

A component of the pathname specified in the sockaddr structure does not name an existing file.

The sockaddr structure specifies an empty string as a pathname.

[ENOMEM] Required memory resources were not available. A retry at a later time might succeed.

[ENOTCONN] The socket is connection-oriented but is not connected.

[ENOTDIR] The socket is in the AF_UNIX domain and the pathname in the sockaddr structure contains a component that is not a directory.

[ENOTSOCK] The socket parameter does not refer to a socket.

[EOPNOTSUPP]

The specified value for the flags parameter is not supported for this socket type or protocol.

527186-003 Hewlett-Packard Company 7

31

sendto(2) OSS System Calls Reference Manual

[EPIPE] One of the following conditions occurred:

An attempt was made to send a message on a socket that is shut down for writing.

An attempt was made to send a message on a connection-oriented socket and the peer socket is closed or shut down for reading. The SIGPIPE signal is also sent to the calling process.

[EWOULDBLOCK]

The socket file descriptor is marked nonblocking (O_NONBLOCK is set) and the operation would block.

RELATED INFORMATION

Functions: getsockopt(2), recv(2), recvfrom(2), recvmsg(2), select(2), send(2), sendmsg(2),

setsockopt(2), shutdown(2), socket(2).

STANDARDS CONFORMANCE

The HP implementation does not return the errno values [EISCONN] or [ENOSR].

The following are HP extensions to the XPG4 specification:

The errno value [ECONNRESET] can be returned when the transport-provider process is not available.

7

32 Hewlett-Packard Company 527186-003

System Functions (s and S) setgid(2)

NAME

setgid - Sets the group ID of the calling process

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsecsrl

H-series OSS processes: /G/system/zdllnnn/zsecdll

SYNOPSIS

#include <sys/types.h>

/* Optional except for POSIX.1 */

#include <unistd.h> int setgid(

gid_t gid);

PARAMETERS

gid

Specifies the new group ID.

DESCRIPTION

The setgid( ) function sets the real group ID, effective group ID, and saved-set-group ID of the calling process to the value specified by the gid parameter.

If the process does not have appropriate privileges but the gid parameter is equal to the real group ID or the saved-set-group ID, the setgid( ) function sets the effective group ID to gid; the real group ID and saved-set-group ID remain unchanged.

If the calling process has appropriate privileges, the real group ID and saved-set-group ID are set to gid along with the effective group ID.

The group list of the calling process remains unchanged.

The value of gid must be in the range 0 through 65535.

RETURN VALUES

Upon successful completion, the setgid( ) function returns the value 0 (zero). Otherwise, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the setgid( ) function sets errno to the corresponding value:

[EINVAL]

[EPERM]

The value of the gid parameter is invalid or out of range.

The process lacks appropriate privileges and the gid parameter does not match the real group ID or the saved-set-group ID.

RELATED INFORMATION

Functions: exec(2), getgid(2), setuid(2).

STANDARDS CONFORMANCE

The following are HP extensions to the XPG4 Version 2 specification:

A process without appropriate privileges can set the effective group ID if the new effective group ID matches a group ID in the group list of the process.

527186-003 Hewlett-Packard Company 7

33

setpgid(2) OSS System Calls Reference Manual

NAME

setpgid - Sets the process group ID for job control

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/types.h>

/* optional except for POSIX.1 */

#include <unistd.h> int setpgid(

pid_t pid,

pid_t pgid);

PARAMETERS

pid pgid

Specifies the process whose process group ID is to be changed.

Specifies the new process group ID.

DESCRIPTION

The setpgid( ) function is used either to join an existing process group or to create a new process group within the session of the calling process. The process group ID of a session leader will not change.

The process group ID of the process designated by the pid parameter is set to the value of the

pgid parameter. If pid is 0 (zero), the process ID of the calling process is used. If pgid is 0

(zero), the process ID of the indicated process is used.

Use From the Guardian Environment

Calls to setpgid( ) from Guardian processes are not successful. Such calls return an errno value of [ENOTOSS].

RETURN VALUES

Upon successful completion, the value 0 (zero) is returned. If the call was unsuccessful and initiated by an OSS process, the value -1 is returned and errno is set to indicate the error. If unsuccessful and initiated by a Guardian process, Guardian trap number 5 is set.

ERRORS

If any of the following conditions occurs, the setpgid( ) function sets errno to the corresponding value:

[EACCES]

[EINVAL]

The value of the pid parameter matches the process ID of a child process of the calling process, and the child process has successfully executed one of the exec,

tdm_exec, or tdm_spawn set of functions.

One of the following conditions exists:

The value of the pgid parameter is less than 0 (zero).

The value of the pgid parameter is not a valid OSS process ID.

Either the pgid or pid parameter is out of range.

[ENOTOSS] The calling process is not an OSS process. The requested operation is not supported from the Guardian environment.

7

34 Hewlett-Packard Company 527186-003

System Functions (s and S) setpgid(2)

[EPERM]

[ESRCH]

One of the following conditions exists:

The process indicated by the pid parameter is a session leader.

The value of the pid parameter matches the OSS 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 parameter is valid, but it does not match the OSS process ID of the process indicated by the pid parameter, and there is no process with a process group ID that matches the value of pgid in the same session as the calling process.

The value of the pid parameter does not match the OSS process ID of the calling process or of a child process of the calling process.

RELATED INFORMATION

Functions: exec(2), getpgrp(2), setsid(2), tcsetpgrp(2), tdm_execve(2), tdm_execvep(2),

tdm_spawn(2), tdm_spawnp(2).

STANDARDS CONFORMANCE

The following are HP extensions to the XPG4 Version 2 specification:

The errno value [ENOTOSS] can be returned.

527186-003 Hewlett-Packard Company 7

35

setsid(2) OSS System Calls Reference Manual

NAME

setsid - Creates a new session and sets the process group ID

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/types.h>

/* optional except for POSIX.1 */

#include <unistd.h> pid_t setsid(void);

DESCRIPTION

The setsid( ) function creates a new session when the calling process is not a process group leader. The calling process then becomes the session leader of this session, the process leader of a new process group, and has no controlling terminal. The process group ID of the calling process is set equal to its process ID. The calling process becomes the only process in the new process group and the only process in the new session.

Use From the Guardian Environment

Calls to setsid( ) from Guardian processes are not successful. Such calls return an errno value of

[ENOTOSS].

RETURN VALUES

Upon successful completion, the value of the new process group ID is returned. If the call was unsuccessful and initiated by an OSS process, the value -1 is returned and errno is set to indicate the error. If unsuccessful and initiated by a Guardian process, Guardian trap number 5 is set.

ERRORS

If any of the following conditions occurs, the setsid( ) function sets errno to the corresponding value:

[ENOTOSS] The calling process is not an OSS process. The requested operation is not supported from the Guardian environment.

[EPERM] One of the following conditions exists:

The calling process is already the process group leader.

The process group ID of a process other than the calling process matches the OSS process ID of the calling process.

RELATED INFORMATION

Functions: getpid(2), setpgid(2).

STANDARDS CONFORMANCE

The following are HP extensions to the XPG4 Version 2 specification:

The errno value [ENOTOSS] can be returned.

7

36 Hewlett-Packard Company 527186-003

System Functions (s and S) setsockopt(2)

NAME

setsockopt - Sets socket options

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/socket.h>

[#include <netinet/in.h> ]

[#include <netinet/in6.h> ]

[#include <netdb.h> ]

[#include <netinet/tcp.h>] Required for TCP protocol level

int setsockopt(

int socket,

int level,

int option_name,

const void *option_value,

size_t option_len

);

PARAMETERS

socket level

Specifies the file descriptor for the socket.

Specifies the protocol level at which the option resides. The following values can be specified for the level parameter in an OSS application program:

IPPROTO_IPV6

Set IP protocol-level options defined for an Internet Protocol version 6 (IPv6) socket

IPPROTO_IP Set IP protocol-level options defined for an Internet Protocol version 4 (IPv4) socket

IPPROTO_TCP

Set TCP protocol-level options defined for a socket

SOL_SOCKET

Set socket-level protocol options defined for a socket

To set options at other levels, supply the appropriate protocol number for the protocol controlling the option. Valid protocol numbers can be found in

/etc/protocols.

option_name

Specifies the option to set. The option_name parameter and any specified options are passed uninterpreted to the appropriate protocol module for interpretation.

The sys/socket.h header file defines the socket-level options. Additional header files are required for options at other levels.

The socket-level options can be enabled or disabled.

The IPPROTO_IPV6 (IP protocol-level IPv6) options are:

IPV6_JOIN_GROUP

Enables IPv6 multicast UDP datagrams on a specified interface.

527186-003 Hewlett-Packard Company 7

37

setsockopt(2) OSS System Calls Reference Manual

IPV6_LEAVE_GROUP

Disables IPv6 multicast UDP datagrams on a specified interface.

IPV6_MULTICAST_IF

Specifies the interface (subnet) to use for outbound multicast

UDP datagrams. option_value is an unsigned int.

IPV6_MULTICAST_HOPS

Specifies the hop limit for outbound multicast UDP datagrams.

option_value is an int that is either:

Between 0 and 255 to indicate the maximum number of hops allowed

-1 to indicate that the default value should be used

All other values cause an error and errno is set to [EINVAL].

IPV6_MULTICAST_LOOP

Specifies that the host belongs to the multicast group that it is sending to, and a copy of the datagram should be sent by loopback to the originating host. This is the default behavior.

option_value is an unsigned int.

IPV6_UNICAST_HOPS

Specifies the hop limit for outbound unicast UDP datagrams.

option_value is an int that is either:

Between 0 and 255 to indicate the maximum number of hops allowed

-1 to indicate that the default value should be used

All other values cause an error and errno is set to [EINVAL].

IPV6_V6ONLY

Specifies that AF_INET6 sockets are restricted to IPv6-only communication.

The IPPROTO_IP (IP protocol-level IPv4) options are:

IP_OPTIONS Sets IP options for each outgoing packet. The option_value parameter is a pointer to a list of IP options and values that conforms with RFC 791.

IP_ADD_MEMBERSHIP

Enables IP multicast UDP datagrams on a specified interface.

IP_DROP_MEMBERSHIP

Disables IP multicast UDP datagrams on a specified interface.

IP_MULTICAST_IF

Specifies the interface (subnet) to use for outbound multicast

UDP datagrams. option_value is an unsigned int.

7

38 Hewlett-Packard Company 527186-003

System Functions (s and S)

527186-003

setsockopt(2)

IP_MULTICAST_TTL

Specifies the hop limit for outbound multicast UDP datagrams.

option_value is an int that is either:

Between 0 and 255 to indicate the maximum number of hops allowed

Between 0 and 255 to indicate the maximum number of hops allowed

-1 to indicate that the default value should be used

All other values cause an error and errno is set to [EINVAL].

IP_MULTICAST_LOOP

Specifies that the host belongs to the multicast group that it is sending to, and a copy of the datagram should be sent by loopback to the originating host. This is the default behavior.

option_value is an unsigned int.

The SOL_SOCKET (socket-level protocol) options are:

SO_BROADCAST

Enables or disables sending of broadcast messages. The default value used when the socket is created is 0 (zero), which disables the option.

This option is valid only for AF_INET or AF_INET6 datagram

(UDP) sockets. If this option is specified for sockets of other types, the function call fails and errno is set to [ENOPRO-

TOOPT].

option_value takes an int value. Specifying any nonzero value enables broadcast messages.

SO_DEBUG

Enables or disables recording of debugging information in the underlying protocol modules. The default value used when the socket is created is 0 (zero), which disables the option.

This option is valid only for AF_INET or AF_INET6 sockets.

If this option is specified for sockets of other types, the function call fails and errno is set to [ENOPROTOOPT].

option_value takes an int value. Specifying a nonzero value enables recording of debugging information.

SO_DONTROUTE

Specifies whether outgoing messages should bypass the standard routing facilities and be directed to the appropriate network interface, according to the destination address. The default value used when the socket is created is 0 (zero), which indicates the use of standard routing.

This option is valid only for AF_INET or AF_INET6 sockets.

If this option is specified for sockets of other types, the function call fails and sets errno to [ENOPROTOOPT].

option_value takes an int value. Specifying any nonzero value bypasses normal routing.

Hewlett-Packard Company 7

39

setsockopt(2) OSS System Calls Reference Manual

SO_KEEPALIVE

Specifies whether to keep connections active by enabling the periodic transmission of messages on a connected socket. The default value used when the socket is created is 0 (zero), which indicates that no periodic messages are sent.

This option is valid only for AF_INET or AF_INET6 sockets.

If this option is specified for sockets of other types, the function call fails and sets errno to [ENOPROTOOPT].

option_value takes an int value. Specifying any nonzero value causes periodic transmission of messages.

SO_LINGER Controls whether the system attempts to deliver unsent data that is queued when a call to the close( ) function occurs.

This option is valid only for AF_INET or AF_INET6 sockets.

If this option is specified for sockets of other types, the function call fails and errno is set to [ENOPROTOOPT].

option_value takes a struct linger value, as defined in the

sys/socket.h header file. However, regardless of the option value, SO_LINGER is always enabled.

SO_OOBINLINE

Specifies whether received out-of-band data (data marked urgent) is queued with other data. The default value used for the option when the socket is created is 0 (zero), which indicates that urgent data is delivered separately.

This option is valid only for AF_INET or AF_INET6 sockets.

If this option is specified for sockets of other types, the function call fails and sets errno to [ENOPROTOOPT].

option_value takes an int value. Specifying any nonzero value causes out-of-band data to remain queued with other data.

SO_RCVBUF Sets the receive buffer size in bytes. The default value used for the option when the socket is created is 8K bytes.

This option is valid only for AF_INET or AF_INET6 sockets.

If this option is specified for sockets of other types, the function call fails and errno is set to [ENOPROTOOPT].

option_value takes an int value. Specifying a 0 (zero) value, a negative value, or a value greater than 262144 causes the function call to fail with errno set to [EINVAL].

SO_REUSEADDR

Specifies whether the rules used in validating addresses supplied by a bind( ) function call should allow reuse of local addresses.

The default value used for the option when the socket is created is 0 (zero), which indicates that addresses should not be reused.

option_value takes an int value. Specifying a nonzero value permits addresses to be reused.

7

40 Hewlett-Packard Company 527186-003

System Functions (s and S) setsockopt(2)

SO_REUSEPORT

Specifies whether the rules used in validating ports supplied by a

bind( ) function call should allow reuse of local ports. The default value used for the option when the socket is created is 0

(zero), which indicates that ports should not be reused.

This option is valid only for UDP ports.

This option takes an int value. Specifying a nonzero value permits ports to be reused.

SO_SNDBUF Sets the send buffer size in bytes. The default value used for the option when the socket is created is 8K bytes.

This option is valid only for AF_INET or AF_INET6 sockets.

If this option is specified for sockets of other types, the function call fails and sets errno to [ENOPROTOOPT].

option_value takes an int value. Specifying a 0 (zero) value, a negative value, or a value greater than 262144 causes the function call to fail with errno set to [EINVAL].

The IPPROTO_TCP (TCP protocol-level) options are:

TCP_MAXRXMT

Sets the maximum retransmission timeout value in multiples of

500 milliseconds.

option_value takes an int value. Valid values are in the range 1 through 60. The value specified for this option should be greater than or equal to the value used for the TCP_MINRXMT option.

TCP_MINRXMT

Sets the minimum retransmission timeout value in multiples of

500 milliseconds.

option_value takes an int value. Valid values are in the range 1 through 2400. The value specified for this option should be less than or equal to the value used for the TCP_MAXRXMT option.

TCP_NODELAY

Specifies whether data packets are buffered before transmission.

option_value takes an int value. A nonzero value indicates that data packets should not be buffered. A 0 (zero) value indicates that buffering should occur.

TCP_RXMTCNT

Sets the maximum retransmission count.

option_value takes an int value. Valid values are in the range 1 through 12. When the value specified for this option is multiplied by the value used for the TCP_MAXRMT option and the result is less than the value used for TCP_TOTRXMTVAL, the

TCP connection will be dropped before the

TCP_TOTRXMTVAL value is reached.

527186-003 Hewlett-Packard Company 7

41

setsockopt(2) OSS System Calls Reference Manual

TCP_SACKENA

Specifies whether TCP selective acknowledgments are enabled.

option_value takes an int value. A nonzero value indicates that selective acknowledgments are enabled. A 0 (zero) value indicates that selective acknowledgments should not be used.

TCP_TOTRXMTVAL

Sets the total maximum retransmission duration in multiples of

500 milliseconds. Once the duration is reached, the TCP cpnnection is dropped.

option_value takes an int value. Valid values are in the range 1 through 28800. When the value specified for the

TCP_RXMTCNT option is multiplied by the value used for the

TCP_MAXRMT option and the result is less than the value used for TCP_TOTRXMTVAL, the TCP connection will be dropped before the TCP_TOTRXMTVAL value is reached.

Options at other protocol levels vary in format and name.

option_value

Points to the buffer containing the appropriate option value. For options that can be classified as disabled or enabled, a value of 0 (zero) indicates that the option should be disabled and a value of 1 indicates that the option should be enabled.

option_len

Contains the size of the buffer pointed to by the option_value parameter.

DESCRIPTION

The setsockopt( ) function sets options associated with a socket. Options can exist at multiple protocol levels. The SO_* options are always present at the uppermost socket level.

The setsockopt( ) function provides an application program with the means to control socket communication. An application program can use the setsockopt( ) function to enable debugging at the protocol level, allocate buffer space, control time-outs, or permit socket data broadcasts.

The sys/socket.h header file defines all the SO_* options available to the setsockopt( ) function.

RETURN VALUES

Upon successful completion, the setsockopt( ) function returns the value 0 (zero). Otherwise, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the setsockopt( ) function sets errno to the corresponding value:

[EBADF] The socket parameter is not a valid file descriptor.

[ECONNRESET]

One of the following conditions occurred:

The transport-provider process for this socket is no longer available.

The TCP/IP subsystem for this socket is no longer available.

The connection was forcibly closed by the peer socket.

The socket can only be closed.

7

42 Hewlett-Packard Company 527186-003

System Functions (s and S) setsockopt(2)

[EFAULT]

[EINVAL]

A user-supplied memory buffer cannot be accessed.

One of the following conditions exists:

The specified option is not valid at the specified socket level.

The socket has been shut down.

[ENOBUFS] There was not enough buffer space available to complete the call. A retry at a later time might succeed.

[ENOMEM] Required memory resources were not available. A retry at a later time might succeed.

[ENOPROTOOPT]

The specified option is not supported by the protocol used by the socket.

[ENOTSOCK] The socket parameter does not refer to a socket.

RELATED INFORMATION

Functions: bind(2), endprotoent(3), getprotobynumber(3), getprotoent(3), getsockopt(2), set-

protoent(3), socket(2) socketpair(2).

STANDARDS CONFORMANCE

The HP implementation does not return the errno value [ENOSR].

The following are HP extensions to the XPG4 specification:

Nonzero values other than 1 can be used to set Boolean options.

The SO_DONTROUTE and SO_REUSEPORT options are supported.

The errno value [ECONNRESET] can be returned when the transport-provider process is unavailable.

Some of the documented uses of the errno value [ENOPROTOOPT] are not described in the specification.

527186-003 Hewlett-Packard Company 7

43

setuid(2) OSS System Calls Reference Manual

NAME

setuid - Sets the user ID of the calling process

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsecsrl

H-series OSS processes: /G/system/zdllnnn/zsecdll

SYNOPSIS

#include <sys/types.h>

/* optional except for POSIX.1 */

#include <unistd.h> int setuid(

uid_t uid);

PARAMETERS

uid

Specifies the new user ID.

DESCRIPTION

When invoked by processes with appropriate privileges, the setuid( ) function sets the real user

ID, effective user ID, and saved-set-user ID of the calling process to the value of the uid parameter.

To change the real user ID, the effective user ID, and the saved-set-user ID, the calling process must have appropriate privileges. If the process does not have appropriate privileges but the uid parameter is equal to the real user ID or the saved-set-user ID, the setuid( ) function sets the effective user ID to uid; the real user ID and saved-set-user ID remain unchanged.

The value of uid must be in the range 0 through 65535.

NOTES

Changing the effective user ID sets the operating system process access ID (PAID) to the value of the effective user ID.

RETURN VALUES

Upon successful completion, the value 0 (zero) is returned. Otherwise, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the setuid( ) function sets errno to the corresponding value:

[EINVAL]

[EPERM]

The uid parameter is out of range.

The process lacks appropriate privileges, and the uid parameter does not match the real user ID or the saved-set-user ID.

RELATED INFORMATION

Functions: exec(2), getuid(2).

7

44 Hewlett-Packard Company 527186-003

System Functions (s and S) shmat(2)

NAME

shmat - Attaches a shared memory segment to the address space of the calling process

LIBRARY

G-series native OSS processes: /G/system/sysnn/zossksrl

H-series OSS processes: /G/system/zdllnnn/zosskdll

SYNOPSIS

#include <sys/shm.h> void *shmat(

int shmid,

const void *shmaddr,

int shmflag);

PARAMETERS

shmid shmaddr shmflag

Specifies the identifier for the shared memory segment. The identifier is usually returned by a previous call to the shmget( ) function.

Specifies the virtual address at which the process wants to attach the shared memory segment. The process can also specify 0 (zero) to have the system select an appropriate address.

Specifies the following attach flags:

SHM_RND

If the shmaddr parameter is not a null pointer, the system rounds off the address, if necessary.

SHM_RDONLY

The current release of OSS does not support read-only access. If the calling process has read permission, the system attaches the segment for both reading and writing.

DESCRIPTION

The shmat( ) function attaches the shared memory segment identified by the shmid parameter to the virtual address space of the calling process. For the shmaddr parameter, the process can specify an explicit address, or it can specify a null pointer to have the system select the address.

If an explicit address is used and (shmflag & SHM_RND) is not zero, the system attempts to attach the segment at the address given by (shmaddr - ((ptrdiff_t)shmaddr % SHMLBA)). The character % is the C-language modulus (remainder) operator.

If an explicit address is used and (shmflag & SHM_RND) is 0 (zero), the system attempts to attach the segment at the address given by shmaddr.

The current release of OSS does not support read-only access. The segment is attached for reading and writing if (shmflag & SHM_RDONLY) is not zero and the calling process has read permission. If (shmflag & SHM_RDONLY) is 0 (zero) and the calling process has read and write permission, the segment is attached for reading and writing.

Memory can be shared only within the same processor.

Shared memory uses operating system flat segments (permanently mapped shareable data segments). Refer to the Guardian Programmer’s Guide for more information about flat segments.

Address Range

An application that is using the shared memory functions shmat( ) and shmdt( ) to manage a range of virtual addresses should use only these functions to manipulate the range.

The valid range of addresses for the shmaddr parameter can change from one release to the next.

Programs should not contain hard-coded addresses.

527186-003 Hewlett-Packard Company 7

45

shmat(2) OSS System Calls Reference Manual

Shared Segment Memory Alignment

A shared memory segment must be aligned on a region boundary. A region is 32 megabytes

(MB) of virtual memory.

If the function call requests rounding, the value returned for shmaddr is rounded down to the closest multiple of 32 MB. The SHMLBA constant, which traditionally represents the number of bytes in a page of memory, represents the number of bytes in a region in the OSS implementation. SHMLBA is always 32 MB in the OSS implementation.

Number of Shared Segments

A process can attach no more than 13 segments at one time. If an attached segment is larger than a region, the maximum number of attached segments is reduced.

Propagation During Process Creation

Segments attached to a parent process are also attached to a child process created by the fork( ) or tdm_fork( ) function. Segments cannot be shared when a child process is created in a different processor than that used by the parent.

Segments attached to a parent process are detached during the processing of a call to:

Any of the exec or tdm_exec sets of functions

Any of the tdm_spawn set of functions

The resulting child process has no attached shared memory segments.

Use From the Guardian Environment

If called from a Guardian process, the function call fails and errno is set to the value of [ENO-

TOSS].

NOTES

The shared memory identifier, shmid, is not the Guardian environment segid value or segment identifier.

Programs should not be written to depend upon the maximum number of attached shared segments. This limit is subject to change.

The maximum number of attached segments decreases when the size of any attached segment exceeds SHMLBA.

Programs should not be written to depend upon the region size. The region size is subject to change.

Refer to the SEGMENT_ALLOCATE_ procedure description in the Guardian Procedure Calls

Reference Manual for more information about segment limits.

RETURN VALUES

Upon successful completion, the shmat( ) function increments the value of the shm_nattch field in the structure associated with the shared memory identifier of the attached shared memory segment. The starting address for the attached segment is returned.

Otherwise, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the shmat( ) function sets errno to the corresponding value and does not attach the shared memory segment:

[EACCES] The calling process does not have access permission for the requested operation.

7

46 Hewlett-Packard Company 527186-003

System Functions (s and S) shmat(2)

[EINVAL] One of the following is true:

The shmid parameter does not specify a valid shared memory identifier.

The shmaddr parameter is not a null pointer and the value of (shmaddr -

((ptrdiff_t)shmaddr % SHMLBA)) is an invalid address for attaching shared memory.

The shmaddr parameter is not a null pointer, (shmflag & SHM_RND) is

0 (zero), and the value of shmaddr is an invalid address for attaching shared memory.

[EMFILE] An attempt to attach a shared memory segment exceeded the maximum number of attached segments allowed for any one process.

[ENOMEM] One of the following is true:

There was not enough data space available to attach the shared memory segment and allocate the associated low-level data structures.

The shared memory segment has reached its maximum use count (the

shm_nattch field already has its maximum value).

[ENOTOSS] The calling process is not an OSS process. The requested operation is not supported from the Guardian environment.

RELATED INFORMATION

Commands: ipcrm(1), ipcs(1).

Functions: exec(2), _exit(2), fork(2), shmctl(2), shmdt(2), shmget(2), tdm_execve(2),

tdm_execvep(2), tdm_fork(2), tdm_spawn(2), tdm_spawnp(2).

STANDARDS CONFORMANCE

The SHMLBA constant is used for a nontraditional value.

The following are HP extensions to the XPG4 Version 2 specification:

The errno value [ENOTOSS] can be returned.

527186-003 Hewlett-Packard Company 7

47

shmctl(2) OSS System Calls Reference Manual

NAME

shmctl - Performs shared memory control operations

LIBRARY

G-series native OSS processes: /G/system/sysnn/zossksrl

H-series OSS processes: /G/system/zdllnnn/zosskdll

SYNOPSIS

#include <sys/shm.h> int shmctl(

int shmid,

int cmd,

struct shmid_ds *buf);

PARAMETERS

shmid cmd buf

Specifies the shared memory identifier for the segment.

Specifies the type of operation. The possible values for cmd and the operations they perform are as follows:

IPC_RMID

Removes the shared memory identifier and deallocates its associated shmid_ds structure.

This is a restricted operation. The effective user ID of the calling process either must have appropriate privileges or must be equal to the value of the creator’s user ID (shm_perm.cuid field) or the owner’s user ID (shm_perm.uid field) in the associated shmid_ds structure.

IPC_SET

Sets the shared memory identifier by copying selected values in the structure specified by the buf parameter into the corresponding fields in the shmid_ds structure associated with the shared memory identifier.

This is a restricted operation. The effective user ID of the calling process either must have appropriate privileges or must be equal to the value of the creator’s user ID (shm_perm.cuid field) or the owner’s user ID (shm_perm.uid field) in the associated shmid_ds structure.

IPC_STAT

Queries the shared memory identifier by copying the contents of its associated shmid_ds structure into the structure specified by the buf parameter. The calling process must have read access to the segment.

Specifies the address of a shmid_ds structure. This structure is used only with the IPC_STAT and IPC_SET values of the cmd parameter. With IPC_STAT, the results of the query are copied to this structure. With IPC_SET, the values in this structure are used to set certain fields in the shmid_ds structure associated with the shared memory identifier. In either case, the calling process must have allocated the structure before making the call.

7

48 Hewlett-Packard Company 527186-003

System Functions (s and S) shmctl(2)

DESCRIPTION

The shmctl( ) function allows a process to query or set the contents of the shmid_ds structure associated with the specified shared memory identifier. It also allows a process to remove the shared memory identifier and its associated shmid_ds structure. The value of the cmd parameter determines which operation is performed.

The IPC_SET value of the cmd parameter uses the user-supplied contents of the buf structure to set the corresponding fields in the shmid_ds structure associated with the shared memory identifier. The fields are set as follows:

The owner’s user ID field (shm_perm.uid) is set as specified in the input.

The owner’s group ID field (shm_perm.gid) is set as specified in the input.

The access modes field (shm_perm.mode) is set as specified in the low-order nine bits of the corresponding field in the input.

The IPC_SET and IPC_RMID values of the cmd parameter also update the shm_perm.ctime field to the current time.

Use From the Guardian Environment

If called from a Guardian process, the function call fails and errno is set to the value of [ENO-

TOSS].

NOTES

The shared memory identifier, shmid, is not the Guardian environment segid value or segment identifier.

Programs should not be written to depend upon the maximum number of attached shared segments. This limit is subject to change.

The maximum number of attached segments decreases when the size of any attached segment exceeds SHMLBA.

Programs should not be written to depend upon the region size. The region size is subject to change.

Refer to the SEGMENT_ALLOCATE_ procedure description in the Guardian Procedure Calls

Reference Manual for more information about segment limits.

RETURN VALUES

Upon successful completion, the value 0 (zero) is returned. Otherwise, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the shmctl( ) function sets errno to the corresponding value:

[EACCES]

[EFAULT]

The cmd parameter is IPC_STAT, but the calling process does not have read permission.

One of the following conditions exists:

The cmd parameter is IPC_STAT, and either the buf structure is not in the address space of the process or the function cannot write into the buf structure.

527186-003 Hewlett-Packard Company 7

49

shmctl(2) OSS System Calls Reference Manual

The cmd parameter is IPC_SET, and the buf structure is not in the address space of the process.

[EINVAL] One of the following conditions exists:

The shmid parameter does not specify a valid shared memory identifier.

The cmd parameter is not a valid command.

[ENOTOSS] The calling process is not an OSS process. The requested operation is not supported from the Guardian environment.

[EPERM] The cmd parameter is equal to either IPC_RMID or IPC_SET, and the calling process does not have the correct privileges.

RELATED INFORMATION

Commands: ipcrm(1), ipcs(1).

Functions: shmat(2), shmdt(2), shmget(2).

STANDARDS CONFORMANCE

The following are HP extensions to the XPG4 Version 2 specification:

The errno values [EFAULT] and [ENOTOSS] can be returned.

7

50 Hewlett-Packard Company 527186-003

System Functions (s and S) shmdt(2)

NAME

shmdt - Detaches a shared memory segment

LIBRARY

G-series native OSS processes: /G/system/sysnn/zossksrl

H-series OSS processes: /G/system/zdllnnn/zosskdll

SYNOPSIS

#include <sys/shm.h> int shmdt(

const void *shmaddr);

PARAMETERS

shmaddr

Specifies the starting virtual address for the shared memory segment that is to be detached. This is the address returned by a previous shmat( ) function call.

DESCRIPTION

The shmdt( ) function detaches the shared memory segment at the indicated address from the address space of the calling process.

Address Range

An application that is using the shared memory functions shmat( ) and shmdt( ) to manage a range of virtual addresses should use only these functions to manipulate the range.

The valid range of addresses for the shmaddr parameter can change from one release to the next.

Programs should not contain hard-coded addresses.

Cleaning Up Shared Memory Identifiers

A shared memory identifier remains allocated until it is removed. An allocated shared memory identifier is not removed when the last process using it terminates. The user must remove allocated shared memory identifiers that are not attached to processes to avoid wasting shared memory resources.

The status of shared memory identifiers can be checked with the ipcs command. Shared memory identifiers can be removed using the ipcrm command. The associated shared memory segment and data structure are removed only after the final detach operation.

Use From the Guardian Environment

If called from a Guardian process, the function call fails and errno is set to to the value of [ENO-

TOSS].

NOTES

The shared memory identifier is not the Guardian environment segid value or segment identifier.

Programs should not be written to depend upon the maximum number of attached shared segments. This limit is subject to change.

The maximum number of attached segments decreases when the size of any attached segment exceeds SHMLBA.

Programs should not be written to depend upon the region size. The region size is subject to change.

Refer to the SEGMENT_ALLOCATE_ procedure description in the Guardian Procedure Calls

Reference Manual for more information about segment limits.

527186-003 Hewlett-Packard Company 7

51

shmdt(2) OSS System Calls Reference Manual

RETURN VALUES

Upon successful completion, the shmdt( ) function returns the value 0 (zero). The shared memory segment is detached. The value of the shm_nattch field in the structure associated with the shared memory identifier in the shared memory table is decremented.

Otherwise, the shmdt( ) function returns the value -1 and sets errno to indicate the error.

ERRORS

If any of the following conditions occur, the shmdt( ) function sets errno to the corresponding value and does not detach the shared memory segment:

[EINVAL] The shmaddr parameter does not specify the starting address of a shared memory segment.

[ENOTOSS] The calling process is not an OSS process. The requested operation is not supported from the Guardian environment.

RELATED INFORMATION

Commands: ipcrm(1), ipcs(1).

Functions: shmat(2), shmctl(2), shmget(2).

STANDARDS CONFORMANCE

The following is a HP extension to the XPG4 Version 2 specification:

The errno value [ENOTOSS] can be returned.

7

52 Hewlett-Packard Company 527186-003

System Functions (s and S) shmget(2)

NAME

shmget - Creates a new shared memory segment or returns the identifier of an existing shared memory segment

LIBRARY

G-series native OSS processes: /G/system/sysnn/zossksrl

H-series OSS processes: /G/system/zdllnnn/zosskdll

SYNOPSIS

#include <sys/shm.h> int shmget(

key_t key,

size_t size,

int shmflag);

PARAMETERS

key size shmflag

Specifies the key that identifies the shared memory segment. The

IPC_PRIVATE key can be used to ensure the return of a new (unused) shared memory identifier.

Specifies the minimum number of bytes to allocate for the shared memory segment.

Specifies the access mode value to use for the segment, logically ORed with the creation flag value to use for the segment.

The access mode value occupies the least-significant nine bits of the parameter.

These bits can be set by logically ORing any of the following symbolic values defined in the sys/stat.h header file:

S_IRGRP

S_IROTH

S_IRUSR

S_IRWXG

S_IRWXO

S_IRWXU

S_IWGRP

S_IWOTH

S_IWUSR

S_IXGRP

S_IXOTH

S_IXUSR

Refer to the chmod(2) reference page for more information about the correct use of these symbolic values.

The following creation flag values are valid:

IPC_CREAT

If the key does not exist, the shmget( ) function creates a shared memory identifier using the given key.

IPC_CREAT | IPC_EXCL

If the key already exists, the shmget( ) function fails and returns an error notification.

527186-003 Hewlett-Packard Company 7

53

shmget(2) OSS System Calls Reference Manual

DESCRIPTION

The shmget( ) function returns the shared memory identifier for the shared memory segment identified by the key parameter. If the key parameter already has a shared memory identifier associated with it and (shmflag & IPC_CREAT) is 0 (zero), that identifier is returned.

A new shared memory identifier, the associated shared memory table entry, and a new shared memory segment of at least size bytes are created when either of the following is true:

The value IPC_PRIVATE is used for the key parameter.

The key parameter does not already have a shared memory identifier associated with it, and (shmflag & IPC_CREAT) is not 0 (zero).

After creating a new shared memory identifier, the shmget( ) function initializes the shared memory table entry associated with the identifier as follows:

The creator’s user ID field (shm_perm.cuid) and owner’s user ID field (shm_perm.uid) are set equal to the effective user ID of the calling process.

The creator’s group ID field (shm_perm.cgid) and owner’s group ID field

(shm_perm.gid) are set equal to the effective group ID of the calling process.

The least-significant nine bits of the access mode field (shm_perm.mode) are set equal to the least-significant nine bits of the shmflag parameter.

The shared memory segment size field (shm_segsz) is set to the value of the size parameter.

The following fields are all set to 0 (zero):

shm_lpid, the process ID of the latest process that performed a shmat( ),

shmdt( ), or shmctl( ) operation

shm_nattch, the number of processes that currently have this region attached

shm_atime, the time of the last shmat( ) operation

shm_dtime, the time of the last shmdt( ) operation

The shm_ctime field is set equal to the current time. This field is updated when any of the following events occur:

— The shared memory identifier is created.

— The permissions for the shared memory segment are changed.

— The shared memory identifier is removed.

The process ID of the process that created the shared memory identifier (the shm_cpid field) is set to the process ID of the calling process.

The shared memory identifier is used for the following purposes:

It identifies a specific entry in the system-maintained shared memory table.

It allows detection of references to a previously removed shared memory identifier.

7

54 Hewlett-Packard Company 527186-003

System Functions (s and S) shmget(2)

It allows detection of attempts to reference shared memory segments in other processors.

Key Creation

The key represents a user-designated name for a given shared memory segment. Keys are usually selected by calling the ftok( ) function before calling the shmget( ) function. The ftok( ) function returns a key based on a path and an interprocess communications identifier. This key is then passed to the shmget( ) function, which returns a shared memory identifier. The shared memory identifier is then used in calls to the shmat( ) and shmctl( ) functions.

Uniqueness of Identifiers

The system recycles no-longer-used shared memory identifiers after a long time elapses.

Swap File

A shared memory segment is shared through a Guardian environment swap file so that its data remains intact even when no processes include it in their virtual address space. This swap file is temporary. It resides on the local HP NonStop node on the same volume as the swap file for the stack segment of the process creating the shared memory segment. If the stack segment is resident, the code segment of the process is used instead.

Processor or Disk Process Failures

If a processor fails, the following is lost:

All information in the system-maintained shared memory table for that processor

All shared memory segments for that processor

All corresponding swap files

If the disk process controlling the swap file fails, the system monitor causes any process with the corresponding shared memory attached to terminate abnormally. Thereafter, a process cannot successfully call either the shmget( ) or shmat( ) function using the associated shared memory identifier. When either function is called, the shared memory segment and its identifier are removed from the system-maintained shared memory table.

Valid Segment Sizes

A shared memory segment can contain up to 4 regions. A region is 32 megabytes (MB). A shared memory segment can therefore be 1 byte to 128 MB in size.

Number of Shared Segments and Identifiers

The maximum number of shared memory identifiers is determined by the maximum number of processes allowed for the processor. This value cannot exceed the limit

SHMT_MAXENTRIES, which is currently set to 1000.

Cleaning Up Shared Memory Identifiers

A shared memory identifier remains allocated until it is removed. An allocated shared memory identifier is not removed when the last process using it terminates. The user must remove allocated shared memory identifiers that are not attached to processes to avoid wasting shared memory resources.

The status of shared memory identifiers can be checked with the ipcs command. Shared memory identifiers can be removed using the ipcrm command. The associated shared memory segment and data structure are removed only after the final detach operation.

Shared Memory Use Between Environments

Guardian environment processes cannot use OSS environment function calls for access to OSS shared memory segments. Similarly, OSS environment processes cannot use OSS environment function calls for access to Guardian environment shared memory segments. However, OSS environment processes can allocate a Guardian environment shared memory segment and manipulate it using Guardian environment procedure calls. A Guardian environment process and an

OSS environment process can share resources through the Guardian environment shared

527186-003 Hewlett-Packard Company 7

55

shmget(2) OSS System Calls Reference Manual

segment.

Use From the Guardian Environment

If called from a Guardian process, the function call fails and errno is set to the value of [ENO-

TOSS].

NOTES

The shared memory identifier is not the Guardian environment segid value or segment identifier.

Programs should not be written to depend upon the maximum number of attached shared segments. This limit is subject to change.

The maximum number of attached segments decreases when the size of any attached segment exceeds SHMLBA.

Programs should not be written to depend upon the region size. The region size is subject to change.

Refer to the SEGMENT_ALLOCATE_ procedure description in the Guardian Procedure Calls

Reference Manual for more information about segment limits.

RETURN VALUES

Upon successful completion, a nonnegative shared memory identifier is returned. Otherwise, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the shmget( ) function sets errno to the corresponding value:

[EACCES]

[EEXIST]

[EINVAL]

A shared memory identifier already exists for the key parameter, but operation permission as specified by the low-order nine bits of the shmflag parameter was not granted.

A shared memory identifier already exists for the key parameter, but

IPC_CREAT and IPC_EXCL were both set in the shmflag parameter.

One of the following conditions is true:

The value of the size parameter is less than the system-defined minimum or greater than the system-defined maximum (larger than 4 regions).

A shared memory identifier already exists for the key parameter, but the number of bytes allocated for the region is less than size and size is not equal to 0 (zero).

[ENOENT] A shared memory identifier does not exist for the key parameter, and

IPC_CREAT was not set in the shmflag parameter.

[ENOMEM] An attempt was made to create a shared memory identifier and its associated shared memory table entry, but there was not enough physical memory available.

[ENOSPC] An attempt to create a new shared memory identifier exceeded the system limit on the maximum number of identifiers allowed.

[ENOTOSS] The calling process is not an OSS process. The requested operation cannot be performed from the Guardian environment.

7

56 Hewlett-Packard Company 527186-003

System Functions (s and S)

RELATED INFORMATION

Commands: ipcrm(1), ipcs(1).

Functions: ftok(3), shmat(2), shmctl(2), shmdt(2).

STANDARDS CONFORMANCE

The following are HP extensions to the XPG4 Version 2 specification:

The errno value [ENOTOSS] can be returned.

shmget(2)

527186-003 Hewlett-Packard Company 7

57

shutdown(2) OSS System Calls Reference Manual

NAME

shutdown - Shuts down socket send and receive operations

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/socket.h> int shutdown(

int socket,

int how

);

PARAMETERS

socket how

Specifies the file descriptor of the socket.

Specifies the type of shutdown. The values are as follows:

SHUT_RD

Disables further receive operations.

SHUT_RDWR

Disables further send and receive operations.

SHUT_WR

Disables further send operations.

DESCRIPTION

The shutdown( ) function disables receive operations, send operations, or both on the specified socket.

RETURN VALUES

Upon successful completion, the shutdown( ) function returns the value 0 (zero). Otherwise, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the shutdown( ) function sets errno to the corresponding value:

[EBADF] The socket parameter is not a valid file descriptor.

[ECONNRESET]

One of the following conditions occurred:

The transport-provider process for this socket is no longer available.

The TCP/IP subsystem for this socket is no longer available.

The connection was forcibly closed by the peer socket.

The socket can only be closed.

[EINVAL] The value specified for the how parameter is not valid.

[ENOBUFS] There was not enough buffer space available to complete the call. A retry at a later time may succeed.

7

58 Hewlett-Packard Company 527186-003

System Functions (s and S) shutdown(2)

[ENOMEM] Required memory resources were not available. A retry at a later time may succeed.

[ENOTCONN] The socket is not connected.

[ENOTSOCK] The socket parameter does not specify a socket.

RELATED INFORMATION

Functions: getsockopt(2), read(2), recv(2), recvfrom(2), recvmsg(2), select(2), send(2),

sendmsg(2), sendto(2), setsockopt(2), socket(2), write(2).

STANDARDS CONFORMANCE

The HP implementation does not return the errno value [ENOSR].

The following are HP extensions to the XPG4 specification:

The errno value [ECONNRESET] can be returned.

527186-003 Hewlett-Packard Company 7

59

sigaction(2) OSS System Calls Reference Manual

NAME

sigaction - Specifies the action to take upon delivery of a signal

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

[ #include <spthread.h> ]

#include <signal.h> int sigaction(

int signal,

const struct sigaction *action,

struct sigaction *o_action );

PARAMETERS

signal action o_action

Specifies the signal. The signal names are defined in the signal.h header file.

The range of valid signals depends on the requested action.

Points to a sigaction structure that describes the action to be taken upon receipt of the signal identified by the signal parameter.

Points to a sigaction structure that returns the signal action data in effect before the call was made. For the signal action in effect at the time of the sigaction( ) call to be returned, the o_action parameter must not be a null pointer.

DESCRIPTION

The sigaction( ) function allows the calling process to change or examine the action to be taken when a specific signal is delivered to the calling process.

Associated with every signal is a signal-dependent default action. The sigaction( ) function can change this action by causing the receiving process to

Ignore the delivery of a specific signal

Restore the default action for a specific signal

Invoke a signal-catching function (that is, "catch" the signal) in response to the delivery of a specific signal

See the signal(4) reference page for the defined signal names and details about the cause and default action of each defined signal.

Unless you are writing a standard POSIX threads application, omit the spthread.h header file.

Use From the Guardian Environment

If called from a TNS or accelerated Guardian process, the actions of this function are undefined and errno is set to [ENOTOSS].

Specifying the Signal

The signal parameter specifies the signal. All values defined for signals in the signal.h header file are valid if the corresponding action is to restore the default action. All signals can be caught or ignored except the SIGKILL, SIGSTOP, and SIGABEND signals; these signals can neither be caught nor ignored.

7

60 Hewlett-Packard Company 527186-003

System Functions (s and S) sigaction(2)

Specifying the Action

If the action parameter is not a null pointer, it points to a sigaction structure that describes the action to be taken on receipt of the signal specified in the signal parameter.

If the o_action parameter is not a null pointer, it points to a sigaction structure in which the signal action data in effect at the time of the sigaction( ) call is returned.

If the action parameter is a null pointer, signal handling is unchanged; thus, the call can be used to inquire about the current handling of a given signal.

If the previous action for signal was established by the signal( ) function (see the signal(3) reference page), the values of the fields returned in the structure pointed to by o_action are unspecified and should not be depended upon. In particular, o_action->sa_handler is not necessarily the same value passed to the signal( ) function. However, if a pointer to the same structure is passed to a subsequent call to the sigaction( ) function using the action parameter, the signal is handled in the same way as if the original call to signal( ) were repeated.

The sigaction structure is as follows:

struct sigaction { sigset_t sa_mask; void (*sa_handler)(int); int sa_flags;

};

The action is ignored when action is set to the SIG_DFL value for a signal that cannot be caught or ignored.

Specifying the Handler

The sa_handler field in the sigaction structure can have one of the following values, or it can point to a function:

SIG_ABORT Requests that the process terminate abnormally when the signal is delivered.

This value is defined in the signal.h header file.

SIG_DEBUG Requests that the debugger be entered when the signal is delivered. This value is | defined in the signal.h header file.

SIG_DFL

Requests default action to be taken when the signal is delivered; this value is defined in the signal.h header file.

SIG_IGN

Rquests that the signal have no effect on the receiving process; this value is defined in the signal.h header file.

|

A pointer to a function requests that the signal be caught; that is, the signal causes the signalcatching function to be called.

These actions are described in detail in the signal(4) reference page.

Blocking Signals

The sa_mask field in the sigaction structure specifies additional signals to be blocked from delivery while the signal-catching function is executing. The system creates a new signal mask from the existing process signal mask, the sa_mask field, and the delivered signal itself. All the signals in the new signal mask are blocked from delivery while the signal-catching function is executing or until a call is made to the sigprocmask( ), pthread_sigmask( ) (for standard POSIX threads), or sigsuspend( ) function. If and when the signal-catching function returns normally, the original signal mask is restored, regardless of any modifications made by the sigprocmask( ) or

pthread_sigmask( ) function since the signal-catching function was invoked.

527186-003 Hewlett-Packard Company 7

61

sigaction(2) OSS System Calls Reference Manual

The SIGKILL, SIGSTOP, and SIGABEND signals cannot be blocked. If a program attempts to block any of these signals, the system removes them from the signal mask without generating an error. For example, if a call to sigaction( ) tries to block the SIGKILL signal and then a subsequent call returns the signal-handling information in the structure pointed to by the o_action parameter, the returned mask is not the same mask that the original call passed in; the difference is that the returned mask does not include the SIGKILL signal.

Specifying Options

Unless you are using standard POSIX threads, the sa_flags field can have the SA_NOCLDSTOP bit set to specify further control over the actions taken on delivery of a signal. If the signal parameter is SIGCHLD and a child process of the calling process stops, a SIGCHLD signal is sent to the calling process unless SA_NOCLDSTOP is set for SIGCHLD.

Use With Standard POSIX Threads

When using standard POSIX threads, specify the spthread.h header file. The signal.h header file can be omitted.

A multi-threaded process can use the sigaction( ) function to establish thread-specific actions for synchronous signals. Each thread can have its own signal handler routine.

When you use the standard POSIX threads version of sigaction( ):

The sigaction( ) function only modifies behavior for individual threads.

The sigaction( ) function only works for synchronous signals. Attempting to set a signal action for an asynchronous signal is an error. This is true even in a single-threaded process.

The signal mask is manipulated using the following functions: sigemptyset( ),

sigfillset( ), sigaddset( ), sigdelset( ), and sigismember( ).

RETURN VALUES

Upon successful completion of the sigaction( ) function, the value 0 (zero) is returned. Otherwise, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the sigaction( ) function sets errno to the corresponding value and no new signal-catching function is installed:

[EFAULT]

[EINVAL]

The action or o_action parameter points to a location outside of the allocated address space of the process.

One of the following conditions exists:

The signal parameter is not a valid signal number.

An attempt was made to ignore or supply a signal-catching function for the SIGKILL, SIGSTOP, or SIGABEND signal.

[ENOTOSS] The calling process was not an OSS process or a native Guardian process. The requested operation cannot be performed from the Guardian environment by a

TNS or accelerated Guardian process.

RELATED INFORMATION

Commands: kill(1).

Functions: _exit(2), exit(3), kill(2), pause(3), pthread_sigmask(2), setjmp(3), sigaddset(3),

sigdelset(3), sigemptyset(3), sigfillset(3), sigismember(3), signal(3), sigprocmask(2), sig-

suspend(2), umask(2), wait(2).

7

62 Hewlett-Packard Company 527186-003

System Functions (s and S) sigaction(2)

Files: signal(4).

STANDARDS CONFORMANCE

The POSIX standards leave some features to the implementing vendor to define. The following features are affected in the HP implementation:

The ordering of members within the sigaction structure might not match the ordering used in signal.h header files in other environments or on other systems.

The values returned in the fields of the structure pointed to by the o_action parameter when sigaction( ) is called and the previous action for the specified signal was established by the signal( ) function are unspecified in the POSIX.1 standard. These values should therefore not be depended upon other than to pass the address returned in

o_action as the action parameter to another sigaction( ) function; the result is as if the

signal( ) function were repeated.

The action is ignored when the action is set to the SIG_DFL value for a signal that cannot be caught or ignored.

The following are HP extensions to the XPG4 Version 2 specification:

HP has defined several new signals, including SIGABEND. See the signal(4) reference page for a complete list.

The [ENOTOSS] error value is an HP extension.

The spthread.h header file is an HP extension and an HP exception to the IEEE Std

1003.1c-1995, POSIX System Application Program Interface.

HP does not define members of the sigaction structure following sa_flags.

HP does not define the SA_SIGINFO symbolic constant.

HP does not support the Realtime Signals Extension. The errno value [ENOTSUP] is not returned.

527186-003 Hewlett-Packard Company 7

63

sigpending(2) OSS System Calls Reference Manual

NAME

sigpending - Examines pending signals

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <signal.h> int sigpending(

sigset_t *set);

PARAMETERS

set

Points to an object of type sigset_t that returns the set of signals that are blocked from delivery and pending to the calling process.

DESCRIPTION

The sigpending( ) function stores the set of signals that are blocked from delivery and pending to the calling process in the object pointed to by the set parameter.

Because signals can arrive asynchronously, no assumption should be made about the current set of pending signals, based on the value returned by this function in

set.

Use From the Guardian Environment

If called from a TNS or accelerated Guardian process, the actions of this function are undefined and errno is set to [ENOTOSS].

RETURN VALUES

Upon successful completion, the sigpending( ) function returns the value 0 (zero). Otherwise, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the sigpending( ) function sets errno to the corresponding value:

[EFAULT] The set parameter points to a location outside the allocated address space of the process.

[ENOTOSS] The calling process was not an OSS process or a native Guardian process. The

sigpending( ) function cannot be used in the Guardian environment by a TNS or accelerated process.

RELATED INFORMATION

Functions: sigaddset(2), sigdelset(2), sigemptyset(3), sigfillset(2), sigismember(2), sigproc-

mask(2).

Files: signal(4).

STANDARDS CONFORMANCE

The following are HP extensions to the XPG4 Version 2 specification:

The [EFAULT] and [ENOTOSS] errors can be returned.

7

64 Hewlett-Packard Company 527186-003

System Functions (s and S) sigprocmask(2)

NAME

sigprocmask - Changes or examines the signal mask

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <signal.h> int sigprocmask(

int how,

sigset_t *set,

sigset_t *o_set );

PARAMETERS

how

Indicates the manner in which the set of masked signals is changed; it has one of the following values:

set o_set

SIG_BLOCK The resulting set is the union of the current set and the signal set pointed to by the set parameter.

SIG_UNBLOCK

The resulting set is the current set less the signals indicated in the signal set pointed to by the set parameter.

SIG_SETMASK

The resulting set is the signal set pointed to by the set parameter.

Specifies the signal set. If the set parameter is not a null pointer, it points to a set of signals to be used to change the currently blocked set. If the set parameter is a null pointer, the value of the how parameter is not significant and the process signal mask is unchanged; thus, the call can be used to inquire about currently blocked signals.

Returns the existing signal mask. If the o_set parameter is not a null pointer, the signal mask in effect at the time of the call is stored in the variable pointed to by the o_set parameter.

DESCRIPTION

The sigprocmask( ) function is used to change or examine the signal mask of the calling process.

Typical use is to

1.

Call the sigprocmask(SIG_BLOCK) function to block signals during a critical section of code.

2.

Call the sigprocmask(SIG_SETMASK) function at the end of the critical section of code to restore the mask to the previous value returned by the

sigprocmask(SIG_BLOCK) function.

If there are any unblocked signals pending after a call to the sigprocmask( ) function, at least one of those signals will be delivered before the sigprocmask( ) function returns.

The sigprocmask( ) function does not allow the SIGKILL, SIGABEND, or SIGSTOP signals to be blocked. If a program attempts to block any of these signals, the sigprocmask( ) function gives no indication of the error.

Any signal that is generated by an event other than the kill( ) or raise( ) function causes process termination if the signal is blocked. If possible, a saveabend file is created.

527186-003 Hewlett-Packard Company 7

65

sigprocmask(2) OSS System Calls Reference Manual

Use From the Guardian Environment

If called from a TNS or accelerated Guardian process, the actions of this function are undefined and errno is set to [ENOTOSS].

EXAMPLES

The following example shows how to use sigprocmask(SIG_BLOCK) to add the signal SIG-

INT to the signal set named newset and save the old mask. Later, the

sigprocmask(SIG_SETMASK) function restores the mask to the previous value returned by the

sigprocmask(SIG_BLOCK) function.

#include <signal.h> int return_value; sigset_t newset, oldset; sigemptyset(&newset); sigaddset(&newset, SIGINT); return_value = sigprocmask (SIG_BLOCK, &newset, &oldset);

. . .

return_value = sigprocmask (SIG_SETMASK, &oldset, NULL);

RETURN VALUES

Upon successful completion, the sigprocmask( ) function returns the value 0 (zero). If the sig-

procmask( ) function fails, the signal mask of the process is unchanged, the value -1 is returned, and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the sigprocmask( ) function sets errno to the corresponding value:

[EFAULT] The set or o_set parameter points to a location outside the allocated address space of the process.

The value of the how parameter is not equal to one of the defined values.

[EINVAL]

[ENOTOSS] The calling process was not an OSS process or a native Guardian process. The

sigprocmask( ) function cannot be used in the Guardian environment by a TNS or accelerated Guardian process.

RELATED INFORMATION

Functions: kill(2), pthread_sigmask(2), sigaction(2), sigaddset(2), sigdelset(2), sigemp-

tyset(2), sigfillset(2), sigismember(2), sigpending(2), sigsuspend(2).

Files: signal(4).

STANDARDS CONFORMANCE

The following are HP extensions to the XPG4 Version 2 specification:

HP has defined several new signals, including SIGABEND. See the signal(4) reference page for a complete list.

This function can set errno to the value [ENOTOSS].

7

66 Hewlett-Packard Company 527186-003

System Functions (s and S) sigsuspend(2)

NAME

sigsuspend - Changes the set of blocked signals and waits for a signal

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <signal.h> int sigsuspend(

sigset_t *signal_mask );

PARAMETERS

signal_mask

Points to a set of signals to be blocked from delivery to the calling process.

DESCRIPTION

The sigsuspend( ) function replaces the signal mask of the process with the set of signals pointed to by the signal_mask parameter, and then suspends execution of the process until delivery of a signal whose action is either to execute a signal-catching function or to terminate the process.

The sigsuspend( ) function does not allow the SIGKILL, SIGABEND, or SIGSTOP signals to be blocked. If a program attempts to block one of these signals, the sigsuspend( ) function gives no indication of an error.

If delivery of a signal causes the process to terminate, the sigsuspend( ) function does not return.

If delivery of a signal causes a signal-catching function to execute, the sigsuspend( ) function returns after the signal-catching function returns, with the signal mask restored to the set that existed prior to the call to the sigsuspend( ) function.

The sigsuspend( ) function sets the signal mask and waits for an unblocked signal as one atomic operation. This means that signals cannot occur between the operations of setting the mask and waiting for a signal.

In normal use, a signal is blocked by calling the sigprocmask(SIG_BLOCK) function at the beginning of a critical section of code. The process then determines whether there is work for it to do. If no work is to be done, the process waits for work by calling the sigsuspend( ) function with the mask previously returned by the sigprocmask( ) function.

Use From the Guardian Environment

If called from a TNS or accelerated Guardian process, the actions of this function are undefined and errno is set to [ENOTOSS].

RETURN VALUES

If a signal is caught by the calling process and control is returned from the signal-catching function, the calling process resumes execution after the sigsuspend( ) function, which always returns the value -1 and, after finishing normally, sets errno to [EINTR].

ERRORS

If any of the following conditions occur, the sigsuspend( ) function sets errno to the corresponding value:

[EINTR] The sigsuspend( ) function was interrupted by a signal that was caught by the calling process, and control was returned from the signal-catching function.

[ENOTOSS] The calling process was not an OSS process or a native Guardian process. This function cannot be used in the Guardian environment by a TNS or accelerated process.

If the signal_mask parameter points to an invalid location, the sigsuspend( ) function generates an unspecified signal that cannot be blocked or ignored and sends the signal to the process.

527186-003 Hewlett-Packard Company 7

67

sigsuspend(2) OSS System Calls Reference Manual

RELATED INFORMATION

Functions: pause(3), sigaction(2), signal(3), sigprocmask(2).

Files: signal(4).

STANDARDS CONFORMANCE

The following are HP extensions to the XPG4 Version 2 specification:

HP has defined several new signals, including SIGABEND. See the signal(4) reference page for a complete list.

The [ENOTOSS] errno value is an HP extension.

|

7

68 Hewlett-Packard Company 527186-003

System Functions (s and S) sockatmark(2)

NAME

sockatmark - Determines whether a socket is at the out-of-band mark

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/socket.h> int sockatmark(

int socket);

PARAMETERS

socket

Specifies the file descriptor for the socket.

DESCRIPTION

The sockatmark( ) function determines whether the specified socket is at an out-of-band mark in its receive queue data. Calls to the sockatmark( ) function between receive operations allow an application to determine the position of out-of-band data within its received data.

A call to sockatmark( ) does not remove the out-of-band data mark from the data stream.

NOTES

A call to the sockatmark( ) function can be made instead of a call to the ioctl( ) function with a request of SIOCATMARK.

RETURN VALUES

If the protocol has marked the data stream and all data preceeding the mark has been read, the

sockatmark( ) function returns the value 1. If no mark exists or if data precedes the mark in the receive queue, the function call returns the value 0 (zero).

If the sockatmark( ) call fails, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the sockatmark( ) function sets errno to the corresponding value:

[EBADF] The socket parameter is not a valid open file descriptor.

[ECONNRESET]

One of the following conditions occurred:

The transport-provider process for this socket is no longer available.

The TCP/IP subsystem for this socket is no longer available.

The connection was forcibly closed by the peer socket.

The socket can only be closed.

[ENOBUFS] There was not enough buffer space available to complete the call. A retry at a later time might succeed.

[ENOMEM] Required memory resources were not available. A retry at a later time might succeed.

[ENOTTY] The socket parameter does not refer to a socket.

527186-003 Hewlett-Packard Company 7

69

sockatmark(2)

RELATED INFORMATION

Functions: recv(2), recvmsg(2), socket(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 specification.

OSS System Calls Reference Manual

7

70 Hewlett-Packard Company 527186-003

System Functions (s and S) socket(2)

NAME

socket - Creates an endpoint for communications

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/socket.h> int socket(

int domain,

int type,

int protocol

);

PARAMETERS

domain type protocol

Specifies the address family of the communications domain in which the socket is to be created.

Specifies the type of socket to be created.

Specifies a particular protocol to be used with the created socket. Specifying a

protocol of 0 (zero) causes the socket( ) function to default to the typical protocol used for the requested socket type. If a nonzero value is specified for proto-

col, it must specify a protocol that is supported by the address family specified by the domain parameter.

DESCRIPTION

The socket( ) function creates an unbound socket in a specified communications domain and returns a file descriptor for the socket that can be used in later function calls that operate on sockets.

The domain parameter specifies the address family used in the communications domain. The address families supported are:

AF_INET

IPv4 Internet addresses. The value PF_INET can also be used to specify this address family.

AF_INET6

IPv6 Internet addresses. The value PF_INET6 can also be used to specify this address family.

AF_UNIX

UNIX pathnames. The values PF_UNIX, AF_LOCAL, and PF_LOCAL can also be used to specify this address family.

The type parameter specifies the socket type, which determines the semantics of communications over the socket. The socket types supported are:

SOCK_DGRAM

Provides datagrams, which are connectionless, unreliable messages of a fixed maximum length.

SOCK_STREAM

Provides sequenced, reliable, two-way, connection-oriented byte streams with a transmission mechanism for out-of-band data.

The documentation for specific address families specifies which socket types each family supports. The sys/socket.h header file contains definitions for socket domains, types, and protocols.

527186-003 Hewlett-Packard Company 7

71

socket(2) OSS System Calls Reference Manual

Socket-level options control socket operations. The getsockopt( ) and setsockopt( ) functions are used to get and set these options, which are defined in the sys/socket.h file.

Use From the Guardian Environment

The socket( ) function is one of a set of functions that have these effects when the first of them is called from the Guardian environment:

Two Guardian file system file numbers (not necessarily the next two available) are allocated for the root directory and the current working directory. These file numbers cannot be closed by calling the Guardian FILE_CLOSE_ procedure.

The current working directory is assigned from the VOLUME attribute of the Guardian environment =_DEFAULTS DEFINE.

The use of static memory by the process increases slightly.

These effects occur only when the first of the set of functions is called. The effects are not cumulative.

Choosing the Transport-Provider Process

Each socket declared by a user process is supported by:

An OSS transport agent process (one per processor)

A domain-specific transport-provider process (one or more per node)

Each user process has a current transport-provider name for each domain that is used when creating a socket in that domain.

The default AF_INET or AF_INET6 transport-provider name is $ZTC0, unless overridden by an existing Guardian DEFINE =TCPIPˆPROCESSˆNAME. If =TCPIPˆPROCESSˆNAME exists, it must be a MAP DEFINE with a FILE attribute string of the desired AF_INET or AF_INET6 transport-provider name.

The default AF_UNIX transport-provider name is $ZPLS, the only supported AF_UNIX transport-provider name.

Each user process can change its AF_INET or AF_INET6 transport-provider name with the

socket_transport_name_set( ) function and can retrieve its current AF_INET, AF_INET6, and

AF_UNIX transport-provider names with the socket_transport_name_get( ) function.

Changing the AF_UNIX transport-provider name is not supported. Changing the AF_INET or

AF_INET6 transport-provider name is meaningful when a node is configured with multiple

TCP/IP processes as part of the AF_INET or AF_INET6 socket environment.

Preventing Memory Conflicts

OSS socket applications use QIO shared memory to exchange data with the OSS transport agent.

QIO uses some areas of memory for internal message processing, and it is necessary to prevent

OSS socket applications from using overlapping memory ranges. Do either of these things to prevent memory conflicts between your socket application and QIO:

If possible, do not specify a flat segment address; instead allow the operating system to allocate a starting region for you by specifying a null pointer as the second parameter in the call to the shmat( ) function, as shown: char *base_Ptr = shmat(shmid, (void*) 0, shmflag);

7

72 Hewlett-Packard Company 527186-003

System Functions (s and S) socket(2)

If you do assign a base address, do not use any address in the range

0x20000000 through

0x41FFFFFF or any of these flat segment regions:

0x20000000 0x22000000 0x24000000 0x26000000

0x28000000 0x2A000000 0x2C000000 0x2E000000

0x30000000 0x32000000 0x34000000 0x36000000

0x38000000 0x3A000000 0x3C000000 0x3E000000

0x40000000 0x42000000 0x44000000 0x46000000

0x48000000 0x4A000000 0x4C000000 0x4E000000

On some processors, QIO allocates its shared memory region by default starting at

0x20000000

, so a QIO configuration of 544 megabytes uses the flat segment regions listed previously. If you use a null pointer instead of specifying the base address, the operating system allocates flat segments for your application starting from the topmost region downward. As a result, OSS socket applications can safely allocate flat segments in any of the upper regions of memory on that processor.

If a memory conflict error still occurs, either you must change the memory allocation for your application or your system administrator must reconfigure QIO.

For more information on the shmat( ) function, see the shmat(2) reference page. For more information on memory addressing, see the Guardian Programmer’s Guide and the server description manual appropriate for your system.

RETURN VALUES

Upon successful completion, the socket( ) function returns the file descriptor for the socket. Otherwise, the value -1 is returned, and errno is set to indicate the error.

ERRORS

If any of these conditions occurs, the socket( ) function sets errno to the corresponding value:

[EACCES] The process does not have appropriate privileges to create the socket.

[EAFNOSUPPORT]

The specified address family is not supported.

[EDEFINEERR]

The Guardian DEFINE =TCPIPˆPROCESSˆNAME is invalid, and the DEFINE was used in an attempt to set the transport-provider name.

[EMFILE]

[ENFILE]

No more file descriptors are available for this process.

The maximum number of file descriptors for this processor are already open.

[ENOBUFS] There was not enough buffer space available to complete the call. A retry at a later time might succeed.

[ENOENT] One of these configuration errors might have occurred:

A requested transport provider process is not available.

An initialization error occurred because of a QIO address conflict.

An initialization error occurred because of a parallel TCP/IP address conflict.

The name of an unavailable transport-provider process can be obtained by a call to the socket_transport_name_get( ) function.

527186-003 Hewlett-Packard Company 7

73

socket(2) OSS System Calls Reference Manual

[ENOMEM] Required memory resources were not available. A retry at a later time might succeed.

[EPROTONOSUPPORT]

The specified address family does not support the specified protocol.

[EPROTOTYPE]

The specified socket type is not supported by the protocol.

[ETANOTRUNNING]

The OSS transport agent for this processor is not running.

This error also can occur when the calling process has migrated to a new processor that does not have a transport agent to support sockets. The socket can only be closed.

RELATED INFORMATION

Functions: accept(2), bind(2), connect(2), getsockname(2), getsockopt(2), listen(2), recv(2),

recvfrom(2), recvmsg(2), send(2), sendmsg(2), sendto(2), setsockopt(2), shmat(2), shut-

down(2), socketpair(2), socket_transport_name_get(2), socket_transport_name_set(2).

STANDARDS CONFORMANCE

The HP implementation does not return the errno value [ENOSR].

The HP implementation does not support the SOCK_SEQPACKET socket type.

HP extensions to the XPG4 specification are:

The errno values [EDEFINEERR], [ENOENT], and [ETANOTRUNNING] can be returned.

7

74 Hewlett-Packard Company 527186-003

System Functions (s and S) socketpair(2)

NAME

socketpair - Creates a pair of connected sockets

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/socket.h> int socketpair(

int domain,

int type,

int protocol,

int socket_vector[2]

);

PARAMETERS

domain type protocol

Specifies the communications domain in which the sockets are created. This parameter must be set to AF_UNIX.

Specifies the type of sockets to create.

Specifies the communications protocol that the socket pair will use. Specifying a value of 0 (zero) for this parameter causes the socketpair( ) function to default to the typical protocol used for the requested socket type.

socket_vector

Specifies a 2-integer array used to hold the file descriptors of the socket pair created with this function call.

DESCRIPTION

The socketpair( ) function creates an unbound pair of connected sockets in the domain specified by the domain parameter, of the type specified by the type parameter, under the protocol optionally specified by the protocol parameter.

The two sockets created by the socketpair( ) function are identical. The file descriptors for the socket pair are returned in socket_vector[0] and socket_vector[1].

The domain parameter specifies the address family used in the communications domain. The

socketpair( ) function supports only the AF_UNIX address family, which supports the use of

UNIX pathnames.

The type parameter specifies the socket type, which determines the communication semantics that the socket pair will use. The socket types supported are:

SOCK_DGRAM

Provides datagrams, which are connectionless, unreliable messages of a fixed maximum length.

SOCK_STREAM

Provides sequenced, reliable, two-way, connection-oriented byte streams with a transmission mechanism for out-of-band data.

The documentation for specific address families specifies which socket types each family supports. The sys/socket.h header file contains definitions for socket domains, types, and protocols.

Socket-level options control socket operations. The getsockopt( ) and setsockopt( ) functions are used to get and set these options, which are defined in the sys/socket.h file.

527186-003 Hewlett-Packard Company 7

75

socketpair(2) OSS System Calls Reference Manual

Use From the Guardian Environment

The socketpair( ) function is one of a set of functions that have these effects when the first of them is called from the Guardian environment:

Two Guardian file system file numbers (not necessarily the next two available) are allocated for the root directory and the current working directory. These file numbers cannot be closed by calling the Guardian FILE_CLOSE_ procedure.

The current working directory is assigned from the VOLUME attribute of the Guardian environment =_DEFAULTS DEFINE.

The use of static memory by the process increases slightly.

These effects occur only when the first of the set of functions is called. The effects are not cumulative.

NOTES

Preventing Memory Conflicts

OSS socket applications use QIO shared memory to exchange data with the OSS transport agent.

QIO uses some areas of memory for internal message processing, and it is necessary to prevent

OSS socket applications from using overlapping memory ranges. Do either of the following things to prevent memory conflicts between your socket application and QIO:

If possible, do not specify a flat segment address; instead allow the operating system to allocate a starting region for you by specifying a null pointer as the second parameter in the call to the shmat( ) function, as shown: char *base_Ptr = shmat(shmid, (void*) 0, shmflag);

If you do assign a base address, do not use any address in the range

0x20000000 through

0x41FFFFFF or any of these flat segment regions:

0x20000000 0x22000000 0x24000000 0x26000000

0x28000000 0x2A000000 0x2C000000 0x2E000000

0x30000000 0x32000000 0x34000000 0x36000000

0x38000000 0x3A000000 0x3C000000 0x3E000000

0x40000000 0x42000000 0x44000000 0x46000000

0x48000000 0x4A000000 0x4C000000 0x4E000000

On some processors, QIO allocates its shared memory region by default starting at

0x20000000

, so a QIO configuration of 544 megabytes uses the flat segment regions listed previously. If you use a null pointer instead of specifying the base address, the operating system allocates flat segments for your application starting from the topmost region downward. As a result, OSS socket applications can safely allocate flat segments in any of the upper regions of memory on that processor.

If a memory conflict error still occurs, either you must change the memory allocation for your application or your system administrator must reconfigure QIO.

For more information on the shmat( ) function, see the shmat(2) reference page. For more information on memory addressing, see the Guardian Programmer’s Guide and the server description manual appropriate for your system.

7

76 Hewlett-Packard Company 527186-003

System Functions (s and S) socketpair(2)

RETURN VALUES

Upon successful completion, the socketpair( ) function returns the value 0 (zero). Otherwise, the value -1 is returned, and errno is set to indicate the error.

ERRORS

If any of these conditions occurs, the socketpair( ) function sets errno to the corresponding value:

[EACCES] The process does not have appropriate privileges to create a socket.

[EAFNOSUPPORT]

The specified address family is not supported.

[EFAULT]

[EMFILE]

A user-supplied memory buffer cannot be accessed or written.

No more file descriptors are available for this process.

[ENFILE] The maximum number of file descriptors for this processor are already open.

[ENOBUFS] There was not enough buffer space available to complete the call. A retry at a later time might succeed.

[ENOENT] One of these configuration errors might have occurred:

A requested transport provider process is not available.

An initialization error occurred because of a QIO address conflict.

An initialization error occurred because of a parallel TCP/IP address conflict.

The name of an unavailable transport-provider process can be obtained by a call to the socket_transport_name_get( ) function.

[ENOMEM] Required memory resources were not available. A retry at a later time might succeed.

[EOPNOTSUPP]

The specified protocol does not permit the creation of socket pairs.

[EPROTONOSUPPORT]

The specified address family does not support the specified protocol.

[EPROTOTYPE]

The specified socket type is not supported by the protocol.

[ETANOTRUNNING]

The OSS transport agent for this processor is not running.

This error can also occur when the calling process has migrated to a new processor that does not have a transport agent to support sockets. The socket can only be closed.

RELATED INFORMATION

Functions: accept(2), bind(2), connect(2), getsockname(2), getsockopt(2), listen(2), recv(2),

recvfrom(2), recvmsg(2), send(2), sendmsg(2), sendto(2), setsockopt(2), shutdown(2),

socket(2), socket_transport_name_get(2), socket_transport_name_set(2).

527186-003 Hewlett-Packard Company 7

77

socketpair(2) OSS System Calls Reference Manual

STANDARDS CONFORMANCE

The HP implementation does not support the SOCK_SEQPACKET socket type.

The HP implementation does not return the errno value [ENOSR].

HP extensions to the XPG4 specification are:

The errno values [ENOENT] and [ETANOTRUNNING] can be returned.

7

78 Hewlett-Packard Company 527186-003

System Functions (s and S) socket_transport_name_get(2)

NAME

socket_transport_name_get - Gets the name of the transport-provider process

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/socket.h> int socket_transport_name_get(

int domain,

char *buffer,

int maxlen

);

PARAMETERS

domain

Specifies the domain for which the transport-provider process name should be obtained. The following values are valid:

buffer maxlen

AF_INET

Specifies the Internet domain using IPv4 addresses

AF_INET6

Specifies the Internet domain using IPv6 addresses

AF_UNIX

Specifies the local sockets domain

Points to the buffer to contain the null-terminated transport-provider process name.

Specifies the length in bytes of the buffer pointed to by the buffer parameter.

This value should be at least 9 so that the buffer is large enough to contain the null terminator and an 8-character process name.

DESCRIPTION

The socket_transport_name_get( ) function returns the name of the transport-provider process for the indicated domain as set by the most recent call to the socket_transport_name_set( ) function, or it returns the default value if no calls to the socket_transport_name_set( ) function have been made. The default transport-provider processes for each domain are as follows:

AF_INET or AF_INET6

The default transport-provider process is $ZTC0, unless overridden by an existing Guardian DEFINE =TCPIPˆPROCESSˆNAME.

AF_UNIX

The default transport-provider process is $ZPLS. This is the only supported

AF_UNIX transport-provider name.

The value returned in the buffer pointed to by the buffer parameter is always an uppercase name.

NOTES

Choosing the Transport-Provider Process

Each socket declared by a user process is supported by:

An OSS transport agent process (one per processor)

A domain-specific transport-provider process (one or more per node)

Each user process has a current transport-provider name for each domain that is used when creating a socket in that domain.

527186-003 Hewlett-Packard Company 7

79

socket_transport_name_get(2) OSS System Calls Reference Manual

The default AF_INET or AF_INET6 transport-provider name is $ZTC0, unless overridden by an existing Guardian DEFINE =TCPIPˆPROCESSˆNAME. If =TCPIPˆPROCESSˆNAME exists, it must be a MAP DEFINE with a FILE attribute string of the desired AF_INET or AF_INET6 transport-provider name.

The default AF_UNIX transport-provider name is $ZPLS. This is the only supported AF_UNIX transport-provider name.

Each user process can change its AF_INET or AF_INET6 transport-provider name with the

socket_transport_name_set( ) function and can retrieve its current AF_INET, AF_INET6, and

AF_UNIX transport-provider names with the socket_transport_name_get( ) function.

Changing the AF_UNIX transport-provider name is not supported. Changing the AF_INET or

AF_INET6 transport-provider name is meaningful when a node is configured with multiple

TCP/IP processes as part of the AF_INET or AF_INET6 socket environment.

The transport-provider name is a convention and does not guarantee use of a specific TCP/IP stack. For example, on older systems, $ZTC0 provided only Internet Procol version 4 addressing for an AF_INET stack and could be used to distinguish the stack to use for sockets that do not use AF_INET6 features. On current systems, $ZTC0 might identify an AF_INET6 protocol stack; check with your TCP/IP administrator to determine your site’s naming conventions before using this function to distinguish between stacks.

RETURN VALUES

Upon successful completion, the socket_transport_name_get( ) function returns the value 0

(zero). Otherwise, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the socket_transport_name_get( ) function sets errno to the corresponding value:

[EDEFINEERR]

The Guardian DEFINE =TCPIPˆPROCESSˆNAME is invalid.

[EFAULT] The address specified for the buffer parameter is not valid.

[EINVAL] One of the following conditions occurred:

The domain parameter does not specify a supported domain.

The buffer specified by the buffer and maxlen parameters is too small to hold the transport-provider process name.

RELATED INFORMATION

Functions: socket_transport_name_set(2), socket(2), socketpair(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 specification.

7

80 Hewlett-Packard Company 527186-003

System Functions (s and S) socket_transport_name_set(2)

NAME

socket_transport_name_set - Sets the name of the transport-provider process

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/socket.h> int socket_transport_name_set(

int domain,

char *buffer

);

PARAMETERS

domain

Specifies the domain for which the transport-provider process name is being set.

The following values are valid:

buffer

AF_INET

Specifies the Internet domain using IPv4 addresses

AF_INET6

Specifies the Internet domain using IPv6 addresses

AF_UNIX

Specifies the local sockets domain

Points to the buffer that contains the null-terminated transport-provider process name. The buffer should be at most 9 characters long, to contain an 8-character process name and a null terminator. The name can be specified in lowercase letters; the name is always stored in uppercase characters.

DESCRIPTION

The socket_transport_name_set( ) function sets the name of the transport-provider process for the domain specified by the domain parameter. A subsequent call to the

socket_transport_name_get( ) function can obtain the value set by this function.

Standard socket behavior does not require use of this function. A default transport-provider process always exists for each domain that provides sockets, as follows:

AF_INET or AF_INET6

The default transport-provider process is $ZTC0, unless overridden by an existing Guardian DEFINE =TCPIPˆPROCESSˆNAME.

AF_UNIX

The default transport-provider process is $ZPLS. This is the only supported

AF_UNIX transport-provider name.

NOTES

This function is equivalent to the socket_set_inet_name( ) function in the Guardian sockets library.

The process name specified in the socket_transport_name_set( ) function call is validated during each call to the socket(), socketpair( ), or socket_transport_name_get( ) function. Process names are not validated during calls to the socket_transport_name_set( ) function.

Choosing the Transport-Provider Process

Each socket declared by a user process is supported by:

An OSS transport agent process (one per processor)

A domain-specific transport-provider process (one or more per node)

527186-003 Hewlett-Packard Company 7

81

socket_transport_name_set(2) OSS System Calls Reference Manual

Each user process has a current transport-provider name for each domain that is used when creating a socket in that domain.

The default AF_INET or AF_INET6 transport-provider name is $ZTC0, unless overridden by an existing Guardian DEFINE =TCPIPˆPROCESSˆNAME. If =TCPIPˆPROCESSˆNAME exists, it must be a MAP DEFINE with a FILE attribute string of the desired AF_INET or AF_INET6 transport-provider name.

The default AF_UNIX transport-provider name is $ZPLS. This is the only supported transportprovider name.

Each user process can change its AF_INET or AF_INET6 transport-provider name with the

socket_transport_name_set( ) function and can retrieve its current AF_INET, AF_INET6, and

AF_UNIX transport-provider names with the socket_transport_name_get( ) function.

Changing the AF_UNIX transport-provider name is not supported. Changing the AF_INET or

AF_INET6 transport-provider name is meaningful when a node is configured with multiple

TCP/IP processes as part of the AF_INET or AF_INET6 socket environment.

RETURN VALUES

Upon successful completion, the socket_transport_name_set( ) function returns the value 0

(zero). Otherwise, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the socket_transport_name_set( ) function sets errno to the corresponding value:

[EFAULT]

[EINVAL]

The address specified for the buffer parameter is not valid.

One of the following conditions occurred:

The domain parameter does not specify a supported domain.

The null-terminated process name pointed to by the buffer parameter has zero length or is too large for a valid process name.

RELATED INFORMATION

Functions: socket_transport_name_get(2), socket(2), socketpair(2).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 specification.

7

82 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_accept(2)

NAME

spt_accept - Initiates thread-aware accept( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int spt_accept(

int socket,

struct sockaddr *address,

size_t *address_len);

PARAMETERS

See the accept(2) reference page.

DESCRIPTION

This is a thread-aware version of the accept( ) function. The socket must be nonblocking for this function to be thread aware.

The following macro maps spt_accept( ) to accept( ) and has been defined in spthread.h:

#define accept(socket, address, address_len) \ spt_accept(socket, address, address_len)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the accept(2) reference page. The following also applies:

The returned file descriptor is nonblocking.

Value errno is never set to [EWOULDBLOCK].

If the socket becomes invalid (is closed by another thread), -1 is returned with an errno of [EBADF].

If a signal is received via pthread_kill( ) and is not blocked, ignored, or handled, -1 is returned with an errno of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

83

spt_awaitio(2) OSS System Calls Reference Manual

NAME

spt_awaitio - Awaits a tagged I/O file

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> spt_error_t spt_awaitio(

const short filenum,

const long tag,

const long timelimit,

long *count_transferred,

long *error,

void *userdata);

PARAMETERS

filenum

Specifies Guardian file number being waited on

tag timelimit

Specifies tag being waited on

Specifies how many hundredths of a second to wait for a completed I/O:

-1

0 means wait forever means immediate return

count_transferred

Specifies transfer count of completed I/O; set by callback when SPT_SUCCESS is returned.

error userdata

Specifies Guardian error number for I/O; set by callback when SPT_SUCCESS is returned or as described in ERRORS

Specifies address of user data area; the referenced data may be modified by a callback

DESCRIPTION

Awaits a tagged I/O on file number to complete, timeout, or be interrupted (see the

spt_interrupt(2) reference page under RETURN VALUES). The function never cancels I/O.

I/O completes only if SPT_SUCCESS is returned. Multiple threads should not await the same tagged I/O on any given file number.

RETURN VALUES

SPT_SUCCESS

File number was waited on.

SPT_ERROR An error occurred. See ERRORS.

SPT_TIMEDOUT

Time limit has expired. See ERRORS.

SPT_INTERRUPTED

Wait was interrupted. See ERRORS.

7

84 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_awaitio(2)

ERRORS

16

29

40

[EINTR]

filenum is not registered.

filenum < 0 (zero).

timelimit has expired.

Wait was interrupted via spt_interrupt( ), spt_interruptTag( ), or a signal was received via pthread_kill( ) and is not blocked, ignored, or handled.

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

85

spt_close(2) OSS System Calls Reference Manual

NAME

spt_close - Initiates thread-aware close( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int spt_close(

int filedes);

PARAMETERS

See the close(2) reference page.

DESCRIPTION

This is a thread-aware version of the close( ) function. Use spt_close( ) instead of close( ) to ensure proper operation of the various thread-aware IO functions.

The following macro maps spt_close( ) to close( ) and has been defined in spthread.h:

#define close(filedes) spt_close(filedes)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the close(2) reference page.

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

86 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_connect(2)

NAME

spt_connect - Initiates thread-aware connect( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int spt_connect(

int socket,

const struct sockaddr *address,

size_t address_len);

PARAMETERS

See the connect(2) reference page.

DESCRIPTION

This is a thread-aware version of the connect( ) function. The socket must be nonblocking for this function to be thread-aware.

The following macro maps spt_connect( ) to connect( ) and has been defined in spthread.h:

#define connect(socket, address, address_len) spt_connect(socket, address, address_len)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the connect(2) reference page. The following also applies:

Value errno is never set to [EINPROGRESS] or [EALREADY].

If the socket becomes invalid (is closed by another thread), -1 is returned with an errno of [EBADF].

If a signal is received via pthread_kill( ) and is not blocked, ignored, or handled, -1 is returned with an errno of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

87

spt_fclose(2) OSS System Calls Reference Manual

NAME

spt_fclose - Initiates thread-aware fclose( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int spt_fclose(FILE *stream);

PARAMETERS

See the fclose(3) reference page online or in the Open System Services Library Calls Reference

Manual.

DESCRIPTION

This is a thread-aware version of the fclose( ) function. Note that the file descriptor underlying the stream must be nonblocking for this function to be thread-aware.

The following macro maps spt_fclose( ) to fclose( ) and has been defined in spthread.h:

#define fclose(stream) spt_fclose(stream)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the fclose(3) reference page. The following also applies:

Value errno is never set to [EAGAIN] or [EWOULDBLOCK].

If the file descriptor underlying the stream becomes invalid (is closed by another thread),

EOF is returned with an errno of [EBADF].

If a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, EOF is returned with an errno of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

88 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_fd_read_ready(2)

NAME

spt_fd_read_ready - Waits on read-ready file descriptor

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int spt_fd_read_ready(

const int fd,

struct timeval *timeout);

PARAMETERS

fd timeout

Specifies an OSS file descriptor.

On input, the maximum interval to wait for fd ready; if NULL, then no timeout will occur. On output, the interval remaining.

DESCRIPTION

Waits on a file descriptor to be read-ready or have an exception pending.

RETURN VALUES

0 (zero) No error.

[EINTR]

[EINVAL]

A signal was received via pthread_kill( ) and is not blocked, ignored, or handled.

Invalid function argument.

[EBADF] File descriptor not open for reading or closed while being waited on.

[ENOTSUP] Operation not supported on file descriptor.

[ETIMEDOUT]

The timeout has occurred.

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

89

spt_fd_write_ready(2) OSS System Calls Reference Manual

NAME

spt_fd_write_ready - Waits on write-ready file descriptor

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int spt_fd_write_ready(

const int fd,

struct timeval *timeout);

PARAMETERS

fd timeout

Specifies an OSS file descriptor.

On input, specifies the maximum interval to wait for fd ready.

If NULL, specifies that no timeout will occur.

On output, specifies the interval remaining.

DESCRIPTION

Wait on a file descriptor to be write-ready or have an exception pending.

RETURN VALUES

0 (zero) No error.

[EINTR] A signal was received via pthread_kill( ) and is not blocked, ignored, or handled.

[EINVAL]

[EBADF]

Invalid function argument.

File descriptor was not open for writing or was closed while being waited on.

[ENOTSUP] Operation was not supported on file descriptor.

[ETIMEDOUT]

timeout has occurred.

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

90 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_fflush(2)

NAME

spt_fflush - Initiates thread-aware fflush( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int spt_fflush(

FILE *stream);

PARAMETERS

See the fflush(3) reference page either online or in the Guardian C Native Library Calls Refer-

ence Manual.

DESCRIPTION

This is a thread-aware version of the fflush(|) function. The file descriptor underlying the stream must be nonblocking for this function to be thread-aware.

The following macro maps spt_fflush(2) to fflush(3) and has been defined in spthread.h:

#define fflush(stream) spt_fflush(stream)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the fflush(3) reference page. The following also applies:

Value errno is never set to [EAGAIN] or [EWOULDBLOCK].

If the file descriptor underlying stream becomes invalid (is closed by another thread),

EOF is returned with an errno of [EBADF].

If a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, EOF is returned with an errno of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

91

spt_fgetc(2) OSS System Calls Reference Manual

NAME

spt_fgetc - Initiates thread-aware fgetc( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int spt_fgetc(

FILE *stream);

PARAMETERS

See the fgetc(3) reference page either online or in the Guardian C Native Library Calls Refer-

ence Manual.

DESCRIPTION

Thread-aware fgetc(3). The file descriptor underlying the stream must be nonblocking for this function to be thread aware.

The following macro maps spt_fgetc(|) to fgetc(|) and has been defined in spthread.h:

#define fgetc(stream) spt_fgetc(stream)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See fgetc(3) reference page. The following also applies:

Value errno is never set to EAGAIN or EWOULDBLOCK.

If the file descriptor underlying stream becomes invalid (is closed by another thread),

EOF is returned with an errno of [EBADF].

If a signal is received via the pthread_kill(|) function and is not blocked, ignored, or handled, EOF is returned with an errno of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

92 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_fgets(2)

NAME

spt_fgets - Initiates thread-aware fgets( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> char *spt_fgets(

char *string,

int n,

FILE *stream);

PARAMETERS

See the fgets(3) reference page either online or in the Guardian C Native Library Calls Refer-

ence Manual.

DESCRIPTION

This is a thread-aware version of the fgets( ) function. The file descriptor underlying the stream must be nonblocking for this function to be thread aware.

The following macro maps spt_fgets( ) to fgets( ) and has been defined in spthread.h:

#define fgets(string, n, stream) spt_fgets(string, n, stream)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the fgets(3) reference page. The following also applies:

Value errno is never set to [EAGAIN] or [EWOULDBLOCK].

If the file descriptor underlying stream becomes invalid (is closed by another thread),

NULL is returned with an errno of [EBADF].

If a signal is received via pthread_kill(2) and is not blocked, ignored, or handled, NULL is returned with an errno of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

93

spt_fgetwc(2) OSS System Calls Reference Manual

NAME

spt_fgetwc - Initiates thread-aware fgetwc( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int spt_fgetwc(

FILE *stream);

PARAMETERS

See the fgetwc(3) reference page either online or in the Open System Services Library Calls

Reference Manual.

DESCRIPTION

This is a thread-aware version of the fgetwc( ) function. The file descriptor underlying the stream must be nonblocking for this function to be thread aware.

The following macro maps spt_fgetwc( ) to fgetwc( ) and has been defined in spthread.h:

#define fgetwc(stream) spt_fgetwc(stream)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the fgetwc(3) reference page. The following also applies:

Value errno is never set to [EAGAIN] or [EWOULDBLOCK].

If the file descriptor underlying stream becomes invalid (is closed by another thread),

WEOF is returned with an errno of [EBADF].

If a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, WEOF is returned with an errno of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

94 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_FileIOHandler_p(2)

NAME

spt_FileIOHandler_p - Executes callback type required by spt_regFileIOHandler( )

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h>

typedef void (*spt_FileIOHandler_p)(const short filenum,

const long tag, const long count_transferred,

const long error, void *userdata);

PARAMETERS

filenum error userdata

Specifies Guardian file number whose IO has completed

tag

Specifies tag of completed IO

count_transferred

Specifies transfer count of completed IO

Specifies Guardian error number for completed IO

Specifies address of user data area; set when the application called the

spt_awaitio( ) function

DESCRIPTION

Callback type required by the spt_regFileIOHandler() function. The callback is executed in the context of the last running thread; it executes on the stack of the last running thread.

RETURN VALUES

None.

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

95

spt_fork(2) OSS System Calls Reference Manual

NAME

spt_fork - Initiates a thread-aware fork() operation

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> pid_t spt_fork( void );

PARAMETERS

None.

DESCRIPTION

This is a thread-aware version of the fork( ) function call that creates a new process from the current thread.

The following macro maps the spt_fork( ) call to the fork( ) funciton and has been defined in the

spthread.h header file:

#define fork() spt_fork().

RETURN VALUES

See the fork(2) reference page.

RELATED INFORMATION

Functions: fork(2).

STANDARDS CONFORMANCE

This function is an extension to the UNIX98 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

96 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_fprintf(2)

NAME

spt_fprintf - Initiates thread-aware fprintf( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int spt_fprintf(

FILE *stream,

const char *format,

...);

PARAMETERS

See the fprintf(3) reference page either online or in the Open System Services Library Calls

Reference Manual.

DESCRIPTION

This is a thread-aware version of the fprintf( ) function. The file descriptor underlying the stream must be nonblocking for this function to be thread aware.

The following macro maps spt_fprintf( ) to fprintf( ) and has been defined in spthread.h:

#define fprintf spt_fprintf

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the fprintf(3) reference page. The following also applies:

Value errno is never set to [EAGAIN] or [EWOULDBLOCK].

If the file descriptor underlying the stream becomes invalid (is closed by another thread),

-1 is returned with an errno of [EBADF].

If a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, -1 is returned with an errno of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

97

spt_fputc(2) OSS System Calls Reference Manual

NAME

spt_fputc - Thread-aware fputc( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int spt_fputc(

int c,

FILE *stream);

PARAMETERS

See the fputc(3) man page either online or in the Open System Services Library Calls Reference

Manual.

DESCRIPTION

This is a thread-aware version of the fputc( ) function. The file descriptor underlying the stream must be nonblocking for this function to be thread aware.

The following macro maps spt_fputc( ) to fputc( ) and has been defined in spthread.h:

#define fputc(c, stream) spt_fputc(c, stream)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the fputc(3) reference page. The following also applies:

The value of errno is never set to [EAGAIN] or [EWOULDBLOCK].

If the file descriptor underlying the stream becomes invalid (is closed by another thread),

EOF is returned with an errno of [EBADF].

If a signal is received via the pthread_kill( ) function that is not blocked, ignored, or handled, EOF is returned with an errno of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

98 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_fputs(2)

NAME

spt_fputs - Initiates thread-aware fputs( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int spt_fputs(

const char *string,

FILE *stream);

PARAMETERS

See the fputs(3) reference page either online or in the Open System Services Library Calls Refer-

ence Manual.

DESCRIPTION

This is a thread-aware version of the fputs( ) function. The file descriptor underlying the stream must be nonblocking for this function to be thread aware.

The following macro maps spt_fputs( ) to fputs( ) and has been defined in spthread.h:

#define fputs(string, stream) spt_fputs(string, stream)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the fputs(3) reference page. The following also applies:

The value of errno is never set to [EAGAIN] or [EWOULDBLOCK].

If the file descriptor underlying stream becomes invalid (is closed by another thread),

EOF is returned with an errno of [EBADF].

If a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, EOF is returned with an errno of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

99

spt_fputwc(2) OSS System Calls Reference Manual

NAME

spt_fputwc - Thread-aware fputwc( )

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> wint_t spt_fputwc(

wint_t c,

FILE *stream);

PARAMETERS

See fputwc(3) refrence page either online or in the Open System Services Library Calls Refer-

ence Manual.

DESCRIPTION

This is a thread-aware version of the fputwc( ) function. The file descriptor underlying the stream must be nonblocking for this function to be thread aware.

The following macro maps spt_fputwc( ) to fputwc( ) and has been defined in spthread.h:

#define fputwc(c, stream) spt_fputwc(c, stream)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the fputwc(3) reference page. The following also applies:

The value of errno is never set to [EAGAIN] or [EWOULDBLOCK].

If the file descriptor underlying the stream becomes invalid (is closed by another thread),

WEOF is returned with an errno of [EBADF].

If a signal is received via the pthread_kill( ) function that is not blocked, ignored, or handled, WEOF is returned with an errno of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

100 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_fread(2)

NAME

spt_fread - Initiates thread-aware fread( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> size_t spt_fread(

void *pointer,

size_t size,

size_t num_items,

FILE *stream);

PARAMETERS

See the fread(3) reference page either online or in the Open System Services Library Calls

Reference Manual.

DESCRIPTION

This is a thread-aware version of the fread( ) function. The file descriptor underlying the stream must be nonblocking for this function to be thread aware.

The following macro maps spt_fread( ) to fread( ) and has been defined in spthread.h:

#define fread(pointer, size, num_items, stream) spt_fread(pointer, size, num_items, stream)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the fread(3) reference page. The following also applies:

The value of errno is never set to [EAGAIN] or [EWOULDBLOCK].

If the file descriptor underlying stream becomes invalid (is closed by another thread),

EOF is returned with an errno of [EBADF].

If a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, 0 is returned with an errno of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

101

spt_fwrite(2) OSS System Calls Reference Manual

NAME

spt_fwrite - Initiates thread-aware fwrite( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> ssize_t spt_fwrite(

const void *pointer,

size_t size,

size_t num_items,

FILE *stream);

PARAMETERS

See the fwrite(3) reference page either online or in the Open System Services Library Calls

Reference Manual.

DESCRIPTION

This is a thread-aware fwrite( ) function. The file descriptor underlying the stream must be nonblocking for this function to be thread aware.

The following macro maps spt_fwrite( ) to fwrite( ) and has been defined in spthread.h:

#define fwrite(pointer, size, num_items, stream) spt_fwrite(pointer, size, num_items, stream)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the fwrite(3) reference page. The following also applies:

The value of errno is never set to [EAGAIN] or [EWOULDBLOCK].

If the file descriptor underlying stream becomes invalid (is closed by another thread), 0 is returned with an errno of [EBADF].

If a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, 0 is returned with an errno of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

102 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_generateTag(2)

NAME

spt_generateTag - Increments and returns a static long tag

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> long spt_generateTag(void);

PARAMETERS

None.

DESCRIPTION

Increments and returns a static long string appropriate for use as a tag. Note that this long string will eventually wrap, thereby returning tags that may still be in use. For example, if a process calls spt_generateTag( ) 100 times per second, every second, the wrap will occur on the 248th day.

RETURN VALUES

This funciton returns a long tag.

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

103

spt_getc(2) OSS System Calls Reference Manual

NAME

spt_getc - Initiates thread-aware getc( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int spt_getc(

FILE *stream);

PARAMETERS

See the getc(3) reference page either online or in the Open System Services Library Calls Refer-

ence Manual.

DESCRIPTION

This is a thread-aware version of the getc( ) function. The file descriptor underlying the stream must be nonblocking for this function to be thread aware.

The following macro maps spt_fgetc( ) to fgetc( ) and has been defined in spthread.h:

#define getc(stream) spt_getc(stream)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the getc(3) reference page. The following also applies:

The value of errno is never set to [EAGAIN] or [EWOULDBLOCK].

If the file descriptor underlying stream becomes invalid (is closed by another thread),

EOF is returned with an errno of [EBADF].

If a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, EOF is returned with an errno of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

104 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_getchar(2)

NAME

spt_getchar - Executes thread-aware getchar( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int spt_getchar(void);

PARAMETERS

See the getchar(3) reference page either online or in the Open System Services Library Calls

Reference Manual.

DESCRIPTION

This is a thread-aware version of the getchar( ) function. The file descriptor underlying standard input must be nonblocking for this function to be thread aware.

The following macro maps spt_getchar( ) to getchar( ) and has been defined in spthread.h:

#define getchar() spt_getchar()

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the getchar(3) reference page. The following also applies:

The value of errno is never set to [EAGAIN] or [EWOULDBLOCK].

If the file descriptor underlying standard input becomes invalid (is closed by another thread), EOF is returned with an errno of [EBADF].

If a signal is received via the pthread_kill(2 function and is not blocked, ignored, or handled, EOF is returned with an errno of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

105

spt_gets(2) OSS System Calls Reference Manual

NAME

spt_gets - Initiates thread-aware gets( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int spt_gets(

FILE *stream);

PARAMETERS

See the gets(3) reference page either online or in the Open System Services Library Calls Refer-

ence Manual.

DESCRIPTION

This is a thread-aware version of the gets(3) function. The file descriptor underlying standard input must be nonblocking for this function to be thread aware.

The following macro maps spt_gets( ) to gets( ) and has been defined in spthread.h:

#define gets(string) spt_gets(string)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the gets(3) reference page. The following also applies:

The value of errno is never set to [EAGAIN] or [EWOULDBLOCK].

If the file descriptor underlying standard input becomes invalid (is closed by another thread), NULL is returned with an errno of [EBADF].

If a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, NULL is returned with an errno of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

106 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_getTMFConcurrentTransactions(2)

NAME

spt_getTMFConcurrentTransactions - Gets the number of concurrent TMF transactions being used

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int spt_getTMFConcurrentTransactions ( void );

PARAMETERS

None.

DESCRIPTION

This function gets the number of concurrent TMF transactions being used.

RETURN VALUES

Upon successful completion, this function returns as an integer value the number of transactions being used.

RELATED INFORMATION

Functions: spt_setTMFConcurrentTransactions(2).

STANDARDS CONFORMANCE

This function is an extension to the UNIX98 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

107

spt_getw(2) OSS System Calls Reference Manual

NAME

spt_getw - Initiates thread-aware getw( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int spt_getw(

FILE *stream);

PARAMETERS

See the getw(3) reference page either online or in the Open System Services Library Calls Refer-

ence Manual.

DESCRIPTION

This is a thread-aware version of the getw( ) function. The file descriptor underlying the stream must be nonblocking for this function to be thread aware.

The following macro maps spt_getw( ) to getw( ) and has been defined in spthread.h:

#define getw(stream) spt_getw(stream)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the getw(3) reference page. The following also applies:

The value of errno is never set to [EAGAIN] or [EWOULDBLOCK].

If the file descriptor underlying the stream becomes invalid (is closed by another thread),

EOF is returned with an errno of [EBADF].

If a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, EOF is returned with an errno of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

108 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_getwc(2)

NAME

spt_getwc - Initiates thread-aware getwc( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> wint_t spt_getwc(

FILE *stream);

PARAMETERS

See the getwc(3) reference page either online or in the Open System Services Library Calls

Refrence Manual.

DESCRIPTION

This is a thread-aware version of the getwc( ) function. The file descriptor underlying the stream must be nonblocking for this function to be thread aware.

The following macro maps spt_getwc( ) to etwc( ) and has been defined in spthread.h:

#define getwc(stream) spt_getwc(stream)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the getwc(3) reference page. The following also applies:

The value of errno is never set to [EAGAIN] or [EWOULDBLOCK].

If the file descriptor underlying stream becomes invalid (is closed by another thread),

EOF is returned with an errno of [EBADF].

If a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, EOF is returned with an errno of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

109

spt_getwchar(2) OSS System Calls Reference Manual

NAME

spt_getwchar - Initiates thread-aware getwchar( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> wint_t spt_getwchar(void);

PARAMETERS

See the getwchar(3) reference page either online or in the Open System Services Library Calls

Reference Manual.

DESCRIPTION

This is a thread-aware version of the getwchar(3) function. The file descriptor underlying standard input must be nonblocking for this function to be thread aware.

The following macro maps spt_getwchar( ) to getwchar( ) and has been defined in spthread.h:

#define getwchar() spt_getwchar()

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the getwchar(3) reference page. The following also applies:

The value of errno is never set to [EAGAIN] or [EWOULDBLOCK].

If the file descriptor underlying standard input becomes invalid (is closed by another thread), WEOF is returned with an errno of [EBADF].

If a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, WEOF is returned with an errno of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

110 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_INITRECEIVE(2)

NAME

spt_INITRECEIVE - Registers $RECEIVE filename

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> long spt_INITRECEIVE (

const short filenum,

const short receive_depth);

PARAMETERS

filenum

Specifies Guardian file number whose IO has completed

receive_depth

Specifies the maximum number of incoming messages as specified in the filenum value is FILE_OPEN( ) call

DESCRIPTION

This function registers filenum as being managed by the $RECEIVE callback.

RETURN VALUES

This function returns Guardian error numbers, which include:

0

29

29

29

$RECEIVE was successfully registered.

$RECEIVE was already registered prior to this call.

FILE_COMPLETE_SET_( ) addition of $RECEIVE returned nonzero.

Value for filenum not 0.

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

111

spt_interrupt(2) OSS System Calls Reference Manual

NAME

spt_interrupt - Interrupts all threads awaiting input or output

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> spt_error_t spt_interrupt(

const short filenum,

const spt_error_t errorSPT);

PARAMETERS

filenum errorSPT

Specifies the Guardian file number for thev file whose awaiting I/O is to be interrupted.

Specifies SPT error returned to waiting file.

DESCRIPTION

Interrupts all threads awaiting IO on file number. Note the I/O is not cancelled by this function.

Interrupted threads will return from the spt_awaitio( ) function with a return value of error_SPT.

Additionally, the error parameter passed to the spt_awaitio( ) function will be set as shown in the PARAMETERS section.

RETURN VALUES

SPT_SUCCESS

The file number awaiting I/O (if any) was interrupted.

SPT_ERROR Either the value specified for error_SPT is invalid or the value for filenum is less than 0 (zero) or is not registered.

ERRORS

-1

40

[EINTR]

- SPT_ERROR

- SPT_TIMEOUT

- SPT_INTERRUPTED

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

112 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_interruptTag(2)

NAME

spt_interruptTag - Interrupts thread awaiting tagged I/O

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> spt_error_t spt_interruptTag(

const short filenum,

const long tag,

const spt_error_t error_SPT);

PARAMETERS

filenum tag error_SPT

Specifies the Guardian file number for the file whose awaiting I/O is to be interrupted

Specifies tag whose awaiting I/O is to be interrupted

Specifies SPT error returned to awaiting IO

DESCRIPTION

Interrupts the thread awaiting the tagged I/O on file number. Note that the I/O is not cancelled by this function. Interrupted threads will return from the spt_awaitio( ) function with a return value of error_SPT. Additionally, the error parameter passed to spt_awaitio( ) will be set as shown in the ERRORS section.

RETURN VALUES

SPT_SUCCESS

Awaiting IO was interrupted.

SPT_ERROR One of the following conditions exists:

The value of filenum was less than 0 (zero), or no awaiting I/O was found

The value of filenum is not registered

The value for error_SPT is invalid

ERRORS

-1

40

EINTR

SPT_ERROR

SPT_TIMEDOUT

SPT_INTERRUPTED

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

113

spt_OSSFileIOHandler_p(2) OSS System Calls Reference Manual

NAME

spt_OSSFileIOHandler_p - Executes callback type required by the

spt_regOSSFileIOHandler( function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> typedef void (

*spt_OSSFileIOHandler_p)(const int filedes,

const int read,

const int write,

const int error);

PARAMETERS

filedes read write error

Specifies OSS file descriptor of interest

Specifies file descriptor is read ready

Specifies file descriptor is write ready

Specifies file descriptor has an exception pending

DESCRIPTION

This function executes the callback type required by the spt_regOSSFileIOHandler( ) function.

This callback is executed in the context of the last running thread (on the stack of the last running thread).

RETURN VALUES

None.

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

114 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_printf(2)

NAME

spt_printf - Initiates thread-aware printf( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int spt_printf(

const char *format, ...);

PARAMETERS

See the printf(3) reference page either online or in the Open System Services Library Calls

Reference Manual.

DESCRIPTION

This is a thread-aware version of the printf( ) function. The file descriptor underlying standard output must be nonblocking for this function to be thread aware.

The following macro maps spt_printf( ) to printf( ) and has been defined in spthread.h:

#define printf spt_printf

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the printf(3) reference page. The following also applies:

THe value of errno is never set to [EAGAIN] or [EWOULDBLOCK].

If the file descriptor underlying standard output becomes invalid (is closed by another thread), -1 is returned with an errno of [EBADF].

If a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, -1 is returned with an errno of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

115

spt_putc(2) OSS System Calls Reference Manual

NAME

spt_putc - Initiates thread-aware putc( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int spt_putc(

int c,

FILE *stream);

PARAMETERS

See the putc(3) reference page either online or in the Open System Services Library Calls Refer-

ence Manual.

DESCRIPTION

This is a thread-aware version of the putc( ) function. The file descriptor underlying the stream must be nonblocking for this function to be thread-aware.

The following macro maps spt_putc( ) to putc( ) and has been defined in spthread.h:

#define putc(c, stream) spt_putc(c, stream)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the putc(3) reference page. The following also applies:

The value of errno is never set to [EAGAIN] or [EWOULDBLOCK].

If the file descriptor underlying the stream becomes invalid (is closed by another thread),

EOF is returned with an errno of [EBADF].

If a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, EOF is returned with an errno of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

116 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_putchar(2)

NAME

spt_putchar - Initiates thread-aware putchar( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> extern int spt_putchar(

int c);

PARAMETERS

See the putchar(3) reference page either online or in the Open System Services Library Calls

Reference Manual.

DESCRIPTION

This is a thread-aware version of the putchar( ) function. The file descriptor underlying standard output must be nonblocking for this function to be thread-aware.

The following macro maps spt_fputchar( ) to fptchar( ) and has been defined in spthread.h:

#define putchar(c) spt_putchar(c)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the putchar(3) reference page. The following also applies:

The value of errno is never set to [EAGAIN] or [EWOULDBLOCK].

If the file descriptor underlying standard output becomes invalid (is closed by another thread), EOF is returned with an errno of [EBADF].

If a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, EOF is returned with an errno of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

117

spt_puts(2) OSS System Calls Reference Manual

NAME

spt_puts - Initiates thread-aware puts( ) function.

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int spt_puts(

const char *string);

PARAMETERS

See the puts(3) reference page either online or in the Open System Services Library Calls Refer-

ence Manual.

DESCRIPTION

This is a thread-aware version of the puts( ) function. The file descriptor underlying standard output must be nonblocking for this function to be thread-aware.

The following macro maps spt_puts( ) to puts( ) and has been defined in spthread.h:

#define puts(string) spt_puts(string)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, similar to the following:

#define SPT_THREAD_AWARE

RETURN VALUES

See the puts(3) reference page. The following also applies:

The value of errno is never set to [EAGAIN] or [EWOULDBLOCK].

If the file descriptor underlying standard output becomes invalid (is closed by another thread), EOF is returned with an errno of [EBADF].

If a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, EOF is returned with an errno of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

118 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_putw(2)

NAME

spt_putw - Initiates thread-aware putw( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int spt_putw(

int c,

FILE *stream);

PARAMETERS

See the putw(3) reference page either online or in the Open System Services Library Calls Refer-

ence Manual.

DESCRIPTION

This is a thread-aware version of the putw( ) function. The file descriptor underlying the stream must be nonblocking for this function to be thread-aware.

The following macro maps spt_putw( ) to putw( ) and has been defined in spthread.h:

#define putw(c, stream) spt_putw(c, stream)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the putw(3) reference page. The following also applies:

The value of errno is never set to [EAGAIN] or [EWOULDBLOCK].

If the file descriptor underlying the stream becomes invalid (is closed by another thread), a nonzero value is returned with an errno of [EBADF].

If a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, a nonzero value is returned with an errno of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

119

spt_putwc(2) OSS System Calls Reference Manual

NAME

spt_putwc - Initiates thread-aware putwc( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> wint_t spt_putwc(

wint_t c,

FILE *stream);

PARAMETERS

See the putwc(3) reference page either online or in the Open System Services Library Calls

Reference Manual.

DESCRIPTION

This is a thread-aware version of the putwc( ) function. The file descriptor underlying the stream must be nonblocking for this function to be thread-aware.

The following macro maps spt_putwc( ) to putwc( ) and has been defined in spthread.h:

#define putwc(c, stream) spt_putwc(c, stream)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the putwc(3) reference page. The following also applies:

The value of errno is never set to [EAGAIN] or [EWOULDBLOCK].

If the file descriptor underlying the stream becomes invalid (is closed by another thread),

WEOF is returned with an errno of [EBADF].

If a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, WEOF is returned with an errno of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

120 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_putwchar(2)

NAME

spt_putwchar - Initiates thread-aware fputwchar( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> wint_t spt_putwchar(

wint_t c);

PARAMETERS

See the putwchar(3) reference page either online or in the Open System Services Library Calls

Reference Manual.

DESCRIPTION

This is a thread-aware version of the putwchar( ) function. The file descriptor underlying standard output must be non-locking for this function to be thread-aware.

The following macro maps spt_putwchar( ) to putwchar( ) and has been defined in spthread.h:

#define putwchar(c) spt_putwchar(c)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the putwchar(3) reference page. The following also applies:

The value of errno is never set to [EAGAIN] or [EWOULDBLOCK].

If the file descriptor underlying standard output becomes invalid (is closed by another thread), WEOF is returned with an errno of [EBADF].

If a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, WEOF is returned with an errno of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

121

spt_read(2) OSS System Calls Reference Manual

NAME

spt_read - Initiates thread-aware read( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> ssize_t spt_read(

int filedes,

void *buffer,

size_t nbytes);

PARAMETERS

See the read(2) reference page.

DESCRIPTION

This is a thread-aware version of the read( function. Note that file descriptor must be nonblocking for this function to be thread-aware.

The following macro maps spt_read( ) to read( ) and has been defined in spthread.h:

#define read(filedes, buffer, nbytes) \ spt_read((filedes), (buffer), (nbytes))

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the read(2) reference page. The following also applies:

The value of errno is never set to [EWOULDBLOCK] or [EAGAIN].

If the file descriptor becomes invalid (for example, is closed by another thread), -1 is returned with an errno of [EBADF].

If a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, -1 is returned with an errno of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

122 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_readv(2)

NAME

spt_readv - Initiates thread-aware readv( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> ssize_t spt_readv(

int filedes,

struct iovec *iov,

int iov_count);

PARAMETERS

See the readv(2) reference page.

DESCRIPTION

This is a thread-aware version of the readv( ) function. The file descriptor must be nonblocking for this function to be thread-aware.

The following macro maps spt_readv( ) to readv( ) and has been defined in spthread.h:

#define readv(filedes, iov, iov_count) spt_readv(filedes, iov, iov_count)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the readv(2) reference page. The following also applies:

The value of errno is never set to [EWOULDBLOCK] or [EAGAIN].

If the file descriptor becomes invalid (is closed by another thread), -1 is returned with an

errno of [EBADF].

If a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, -1 is returned with an errno of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

123

spt_RECEIVEREAD(2) OSS System Calls Reference Manual

NAME

spt_RECEIVEREAD - Initiates thread-aware function for reading $RECEIVE

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> long spt_RECEIVEREAD(

const short filenum,

char *buffer,

const short read_count,

long *count_read,

const long timelimit,

short *receive_info ,

short *dialog_info);

PARAMETERS

filenum buffer read_count

Specifies the Guardian file number for $RECEIVE (always 0)

Specifies the data buffer

Specifies the number of bytes to read

count_read timelimit

Specifies the number of bytes read

Specifies a FILE_COMPLETE-style time limit

receive_info

Specifies a FILE_GETRECEIVEINFO-style $RECEIVE info structure; NULL may be passed if this information is not needed; must not be NULL if filenum’s

receive_depth is greater than 0 (zero).

dialog_info

Specifies a FILE_GETRECEIVEINFO-style of dialog information (a short int used by context-sensitive Pathway servers); NULL can be passed if this information is not needed; NULL must be passed if receive_info is NULL.

DESCRIPTION

This thread-aware function is specifically for reading $RECEIVE. spt_RECEIVEREAD( ) is slightly patterned after a combination of the READUPDATEX procedure and the

FILE_GETRECEIVEINFO procedure, although its parameters do not match either of its modeled procedures. A side effect of calling spt_RECEIVEREAD )*O puts the calling thread into a

transaction (via a call to the SPT_TMF_SetTxHandle( ) function), if the received message was transactional. The calling thread may be blocked to honor the filenum value’s receive depth.

This allows any number of threads to simultaneously call spt_RECEIVEREAD( ). Blocked threads will be unblocked as other threads complete their calls to the spt_REPLYX( ) function.

NOTES

Processing of the spt_RECEIVEREAD( ) function cannot be interrupted by specifying

spt_interrupt(SPT_INTERRUPTED). The spt_RECEIVEREAD( ) function responds to the attempt by retrying the input or output.

To interrupt the spt_RECEIVEREAD( ) function, use one of the following function calls:

spt_wakeup(0, -1, 0, error) where error is any error number that can be recognized as a return value for the spt_RECEIVEREAD( ) function.

7

124 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_RECEIVEREAD(2)

spt_interrupt(0, SPT_ERROR).

spt_interrupt(0, SPT_TIMEDOUT).

Using any of these calls also cancels the input/output operation.

RETURN VALUES

This function returns Guardian file-system error numbers including:

16 filenum is not registered.

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

125

spt_recv(2) OSS System Calls Reference Manual

NAME

spt_recv - Initiates thread-aware recv( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> ssize_t spt_recv(

int socket,

void *buffer,

size_t length,

int flags);

PARAMETERS

See the recv(2) reference page.

DESCRIPTION

This is a thread-aware version of the recv( ) function. The socket must be nonblocking for this function to be thread-aware.

The following macro maps spt_recv( ) to recv( ) and has been defined in spthread.h:

#define recv(socket, buffer, length, flags) spt_recv(socket, buffer, length, flags)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the recv(2) reference page. The following also applies:

The value of errno is never set to [EWOULDBLOCK].

If the socket becomes invalid (is closed by another thread), -1 is returned with an errno of [EBADF].

If a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, -1 is returned with an errno of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

126 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_recvfrom(2)

NAME

spt_recvfrom - Initiates thread-aware recvfrom( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> ssize_t spt_recvfrom(

int socket,

void *buffer,

size_t length,

int flags,

struct sockaddr *address,

size_t *address_len);

PARAMETERS

See the recvfrom(2) reference page.

DESCRIPTION

This is a thread-aware version of the recvfrom( ) function. The socket must be nonblocking for this function to be thread-aware.

The following macro maps spt_recvfrom( ) to recvfrom( ) and has been defined in spthread.h:

#define recvfrom(socket, buffer, length, flags, address, address_len)\ spt_recvfrom(socket, buffer, length, flags, address, address_len)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the recvfrom(2) reference page. The following also applies:

The value of errno is never set to [EWOULDBLOCK].

If the socket becomes invalid (is closed by another thread), -1 is returned with an errno of [EBADF].

If a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, -1 is returned with an errno of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

127

spt_recvmsg(2) OSS System Calls Reference Manual

NAME

spt_recvmsg - Initiates thread-aware recvmsg(2) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> ssize_t spt_recvmsg(

int socket,

struct msghdr *message,

int flags);

PARAMETERS

See the recvmsg(2) reference page.

DESCRIPTION

This is a thread-aware version of the recvmsg( ) function. The socket must be nonblocking for this function to be thread-aware.

The following macro maps spt_recvmsg( ) to recvmsg( ) and has been defined in spthread.h:

#define recvmsg(socket, message, flags)\ spt_recvmsg(socket, message, flags)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the recvmsg(2) reference page. The following also applies:

The value of errno is never set to [EWOULDBLOCK].

If the socket becomes invalid (is closed by another thread), -1 is returned with an errno value of [EBADF].

If a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, -1 is returned with an errno value of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

128 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_regFile(2)

NAME

spt_regFile - Registers the file number

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> spt_error_t spt_regFile(

const short filenum);

PARAMETERS

filenum

Specifies the Guardian file number of the file being registered

DESCRIPTION

Registers the file number as one that the user will manage through the default callback.

RETURN VALUES

See the spt_regFileIOHandler(2) reference page.

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

129

spt_regFileIOHandler(2) OSS System Calls Reference Manual

NAME

spt_regFileIOHandler - Registers the file number

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> spt_error_t spt_regFileIOHandler(

const short filenum,

const spt_FileIOHandler_p functionPtr);

PARAMETERS

filenum functionPtr

Specifies the Guardian file number for the file being registered

Specifies user-supplied callback. This function must not block its invoking thread; for example, it should not call the spt_awaitio( ) function

DESCRIPTION

This function registers the file number as one that the user will manage through a user-supplied callback. This callback is invoked immediately after each I/O on filenum completes.

RETURN VALUES

SPT_SUCCESS

THe Guardian file number was successfully registered.

SPT_ERROR The value specified for filenum was less than 0 (zero).

SPT_ERROR filenum was already registered prior to this call.

SPT_ERROR The FILE_COMPLETE_SET_ procedure addition of filenum returned a nonzero value.

SPT_ERROR functionPtr is NULL.

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

130 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_regOSSFileIOHandler(2)

NAME

spt_regOSSFileIOHandler - Registers the file descriptor to manage through a callback function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> spt_error_t spt_regOSSFileIOHandler(

const int filedes,

const spt_OSSFileIOHandler_p functionPtr);

PARAMETERS

filedes functionPtr

Specifies the OSS file descriptor being registered

Specifies the user-supplied callback function; this function must not block

DESCRIPTION

This function registers the file descriptor as one that the user will manage through a user-supplied callback.

RETURN VALUES

SPT_SUCCESS

Value for file descriptor was registered.

SPT_ERROR The specified filedes was less than 0 (zero).

SPT_ERROR filedes was already registered prior to this call.

SPT_ERROR functionPtr is NULL.

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

131

spt_regPathsendFile(2) OSS System Calls Reference Manual

NAME

spt_regPathsendFile - Registers the Pathsend file number

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> spt_error_t spt_regPathsendFile(

const short fileno );

PARAMETERS

fileno

Contains the scsend-op-num value obtained during the first nowaited

SERVERCLASS_SEND_, SERVERCLASS_DIALOG_BEGIN_, or

SERVERCLASS_DIALOG_SEND_ procedure call.

DESCRIPTION

This function is used to register the Pathsend file number. This function should be called immediately after the first call to a SERVERCLASS_SEND_,

SERVERCLASS_DIALOG_BEGIN_, or SERVERCLASS_DIALOG_SEND_ procedure call.

RETURN VALUES

SPT_SUCCESS

The Pathsend file number was successfully registered.

SPT_ERROR The specified Pathsend file number is already registered.

STANDARDS CONFORMANCE

This function is an extension to the UNIX98 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

132 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_regPathsendTagHandler(2)

NAME

spt_regPathsendTagHandler - Registers the user-supplied Pathsend tag

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> spt_error_t spt_regPathsendTagHandler(

const long tag,

spt_FileIOHandler_p callback,

void * userdata );

PARAMETERS

tag callback userdata

Specifies the Pathsend tag that should be registered.

Specifies a user-supplied callback function. This function should not block its invoking thread. The callback function should have the following prototype:

callback(const short filenum,

/* Guardian file number being waited on */ const long tag,

/* tag being waited on or

-1 for all tags */ const long completionCount,

/* byte transfer count of completed IO */ const long fserror,

/* Guardian error number for IO */ void * userdata

/* for communication between

I/O initiator and callback. */

);

Specifies data to be communicated between the I/O initiator and the callback function.

DESCRIPTION

This function registers the Pathsend tag as a tag that the user will manage through a user-supplied callback function. The callback function is invoked when a Pathsend operation that uses the tag completes.

RETURN VALUES

SPT_SUCCESS

The specified tag was registered.

SPT_ERROR Another Pathsend handler has already registered the tag.

527186-003 Hewlett-Packard Company 7

133

spt_regPathsendTagHandler(2) OSS System Calls Reference Manual

RELATED INFORMATION

Functions: spt_unregPathsendTagHandler(2),

SPT_SERVERCLASS_DIALOG_ABORT_(2),

SPT_SERVERCLASS_DIALOG_BEGIN_(2), SPT_SERVERCLASS_DIALOG_END_(2),

SPT_SERVERCLASS_DIALOG_SEND_(2), SPT_SERVERCLASS_SEND_INFO_(2),

SPT_SERVERCLASS_SEND_(2).

STANDARDS CONFORMANCE

This function is an extension to the UNIX98 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

134 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_regTimerHandler(2)

NAME

spt_regTimerHandler - Registers a user-supplied timer callback function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> spt_error_t spt_regTimerHandler(

const spt_TimerHandler_p functionPtr);

PARAMETERS

functionPtr

Specifies the user-supplied callback function; this function must not block I/O

DESCRIPTION

This function registers a user-supplied timer callback function.

RETURN VALUES

SPT_SUCCESS

The callback function was successfully registered.

SPT_ERROR functionPtr is NULL.

SPT_ERROR The specified callback function is already registered.

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

135

spt_REPLYX(2) OSS System Calls Reference Manual

NAME

spt_REPLYX - Initiates thread-aware REPLYX procedure call

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> long spt_REPLYX(

const char *buffer,

const short write_count,

short *count_written,

const short msg_tag,

const short error_return);

PARAMETERS

buffer

Specifies data buffer

write_count

Specifies the number of bytes to write

count_written

Specifies the number of bytes written; might be NULL

msg_tag

Specifies required tag identifying message to reply to and is ignored if the corresponding Guardian file number receive depth is 1

error_return

Specifies a Guardian file-system error to return to sender

DESCRIPTION

This is a thread-aware version of the REPLYX procedure call; this function clears the thread’s transaction context if appropriate.

RETURN VALUES

This function returns a Guardian file-system error number.

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

136 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_select(2)

NAME

spt_select - Initiates thread-aware select( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int spt_select(

int nfds,

fd_set *readfds,

fd_set *writefds,

fd_set *errorfds,

struct timeval *timeout);

PARAMETERS

See the select(2) reference page.

DESCRIPTION

This is a thread-aware version of the select( ) function.

The following macro maps spt_select( ) to select( ) and has been defined in spthread.h:

#define select(nfds, readfds, writefds, errorfds, timeout)\ spt_select(nfds, readfds, writefds, errorfds, timeout)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the select(2) reference page. The following also applies:

If the file descriptor becomes invalid (is closed by another thread), -1 is returned with an errno of [EBADF].

If a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, -1 is returned with an errno value of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

137

spt_send(2) OSS System Calls Reference Manual

NAME

spt_send - Initiates thread-aware send( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> ssize_t spt_send(

int socket,

const void *buffer,

size_t length,

int flags);

PARAMETERS

See the send(2) reference page.

DESCRIPTION

This is a thread-aware version of the send( ) function. The socket must be nonblocking for this function to be thread-aware.

The following macro maps spt_send( ) to send( ) and has been defined in spthread.h:

#define send(socket, buffer, length, flags)\ spt_send(socket, buffer, length, flags)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the send(2) reference page. The following also applies:

The value of errno is never set to [EWOULDBLOCK].

If the socket becomes invalid (is closed by another thread), -1 is returned with an errno of [EBADF].

If a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, -1 is returned with an errno value of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

138 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_sendmsg(2)

NAME

spt_sendmsg - Initiates thread-aware sendmsg( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> ssize_t spt_sendmsg(

int socket,

const struct msghdr *message,

int flags);

PARAMETERS

See the sendmsg(2) reference page.

DESCRIPTION

This is a thread-aware version of the sendmsg( ) function. The socket must be nonblocking for this function to be thread-aware.

The following macro maps spt_sendmsg( ) to sendmsg( ) and has been defined in spthread.h:

#define sendmsg(socket, message, flags)\ spt_sendmsg(socket, message, flags)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the sendmsg(2) reference page. The following also applies:

The value of errno is never set to [EWOULDBLOCK].

If the socket becomes invalid (is closed by another thread), -1 is returned with an errno of [EBADF].

If a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, -1 is returned with an errno value of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

139

spt_sendto(2) OSS System Calls Reference Manual

NAME

spt_sendto - Initiates thread-aware sendto( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> ssize_t spt_sendto(

int socket,

const void *buffer,

size_t length,

int flags,

const struct sockaddr *dest_addr,

size_t dest_len);

PARAMETERS

See the sendto(2) reference page.

DESCRIPTION

This is a thread-aware version of the sendto( ) function. The socket must be nonblocking for this function to be thread-aware.

The following macro maps spt_sendto( ) to sendto( ) and has been defined in spthread.h:

#define sendto(socket, buffer, length, flags, dest_addr, dest_len) \ spt_sendto(socket, buffer, length, flags, dest_addr, dest_len)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the sendto(2) reference page. The following also applies:

The value of errno is never set to [EWOULDBLOCK].

If the socket becomes invalid (is closed by another thread), -1 is returned with an errno value of [EBADF].

If a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, -1 is returned with an errno value of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

140 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_setOSSFileIOHandler(2)

NAME

spt_setOSSFileIOHandler - Sets interest in file descriptor

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> extern spt_error_t spt_setOSSFileIOHandler(

const int filedes,

const int read,

const int write,

const int error);

PARAMETERS

filedes read write error

Specifies the OSS file descriptor for the file of interest

Nonzero indicates interest in read ready

Nonzero indicates interest in write ready

Nonzero indicates interest in exception pending

DESCRIPTION

This function sets interest in an OSS file descriptor.

RETURN VALUES

SPT_SUCCESS

This value is returned for any of the following conditions:

The filedes interest was successfully set

The filedes was not registered prior to this call

The specified filedes is invalid

The specified filedes is not supported

SPT_ERROR The specified filedes was less than 0 (zero).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

141

spt_setTMFConcurrentTransactions(2) OSS System Calls Reference Manual

NAME

spt_setTMFConcurrentTransactions - Sets the number of concurrent TMF transactions

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int spt_setTMFConcurrentTransactions (

short max_trans );

PARAMETERS

max_trans

Specifies the maximum number of concurrent transactions desired.

DESCRIPTION

This function sets the maximum number of concurrent TMF transactions.

RETURN VALUES

This function returns 0 (zero) upon successful completion of the call. If an error occurs, this function can return the following value:

EINVAL

Unable to change the maximum number of concurrent transactions because TMF is already processing transactions.

RELATED INFORMATION

Functions: spt_getTMFConcurrentTransactions(2).

STANDARDS CONFORMANCE

This function is an extension to the UNIX98 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

142 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_sleep(2)

NAME

spt_sleep - Suspends execution of the thread for a specified time interval

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> unsigned int spt_sleep (

unsigned int seconds );

PARAMETERS

seconds

Specifies the number of seconds for which the thread is to be suspended.

DESCRIPTION

The spt_sleep( ) function suspends a thread for a specified number of seconds. A certain amount of delay can be expected in the processing of the spt_sleep( ) call because of other processorintensive or input/output-intensive threads. If an unblocked signal is received during the suspension period, spt_sleep( ) returns control immediately and returns the sleep time remaining.

RETURN VALUES

This function can return the following values:

0 (zero)

seconds

The thread was suspended for the full time specified.

Indicates the number of seconds remaining in the specified suspension time.

RELATED INFORMATION

Functions: spt_usleep(2).

STANDARDS CONFORMANCE

This function is an extension to the UNIX98 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

143

spt_system(2) OSS System Calls Reference Manual

NAME

spt_system - Initiates thread-aware system( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int spt_system(

const char *command);

PARAMETERS

See the system(3) reference page either online or in the Open System Services Library Calls

Reference Manual.

DESCRIPTION

This is a thread-aware verison of the system( ) function. All threads in the process are temporarily blocked while the child process, which performs the system( ) call, is created.

The following macro maps spt_system( ) to system( ) and has been defined in spthread.h:

#define system(command) spt_system(command)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the system(3) reference page. Also, if a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, -1 is returned with an errno value of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

144 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_TimerHandler_p(2)

NAME

spt_TimerHandler_p - Executes callback type required by spt_regTimerHandler( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> typedef long (*spt_TimerHandler_p)(void);

PARAMETERS

None.

DESCRIPTION

This function executes a callback type required by the spt_regTimerHandler( ) function. The callback is executed in the context of the last running thread. This means that the callback executes on the stack of the last running thread.

RETURN VALUES

0

-1

>0 (zero)

Callback has readied a thread to run, and will be invoked again as soon as possible.

Callback has not readied a thread, but will be invoked again as soon as possible.

Callback has not readied a thread. Return value is the hundredths of a second until callback should be invoked again.

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

145

SPT_TMF_GetTxHandle(2) OSS System Calls Reference Manual

NAME

SPT_TMF_GetTxHandle - Gets the current TMF transaction handle

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> short SPT_TMF_GetTxHandle(

SPT_TMF_TxHandle_t *tx_handle );

PARAMETERS

tx_handle

Receives the current active TMF transaction handle.

DESCRIPTION

This function retrieves the current active transaction handle of the thread.

RETURN VALUES

This function returns an integer value indicating the result of the call. Possible return values are:

0 (zero)

22

29

75

Successful completion of the call. The current active transaction handle is returned in tx_handle.

A bounds error occurred.

There are missing parameters.

There is no current transaction.

RELATED INFORMATION

Functions: SPT_TMF_SetTxHandle(2), SPT_TMF_Init(2).

STANDARDS CONFORMANCE

This function is an extension to the UNIX98 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

146 Hewlett-Packard Company 527186-003

System Functions (s and S) SPT_TMF_Init(2)

NAME

SPT_TMF_Init - Initializes the tfile for concurrent transaction management

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> short SPT_TMF_Init( void );

PARAMETERS

None.

DESCRIPTION

This function opens the tfile for concurrent transaction management.

RETURN VALUES

SPT_SUCCESS

The TMF file is initialized for concurrent transaction management.

error

Contains the error value returned by the underlying call to the

Guardian OPEN procedure. See the Guardian Procedure Errors

and Messages Manual for more information on the specific value returned.

RELATED INFORMATION

Functions: SPT_TMF_GetTxHandle(2), SPT_TMF_SetTxHandle(2),

spt_getTMFConcurrentTransactions(2), spt_setTMFConcurrentTransactions(2).

STANDARDS CONFORMANCE

This function is an extension to the UNIX98 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

147

SPT_TMF_SetTxHandle(2) OSS System Calls Reference Manual

NAME

SPT_TMF_SetTxHandle - Sets the TMF transaction handle

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> short SPT_TMF_SetTxHandle(

SPT_TMF_TxHandle_t *tx_handle );

PARAMETERS

tx_handle

Specifies the transaction handle of the current TMF transaction.

DESCRIPTION

This function sets the specified transaction handle as the current active transaction for the thread.

RETURN VALUES

This function returns an integer value indicating the result of the call. Possible return values are:

0 (zero)

22

29

75

78

715

Indicates the transaction handle was successfully set.

Indicates that a bounds error occurred.

Indicates missing parameters.

Indicates that there is no current transaction.

Indicates an invalid transaction identifier or that a transaction has not started on this Expand node.

Indicates an invalid transaction handle.

RELATED INFORMATION

Functions: SPT_TMF_GetTxHandle(2), SPT_TMF_Init(2).

STANDARDS CONFORMANCE

This function is an extension to the UNIX98 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file ispthread.h is an HP exception to the POSIX standard.

7

148 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_unregFile(2)

NAME

spt_unregFile - Unregisters a Guardian file number as one that the user manages

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> extern spt_error_t spt_unregFile(

const short filenum);

PARAMETERS

filenum

Specifies the Guardian file number being unregistered

DESCRIPTION

This function unregisters a Guardian file number as one that the user manages. Any threads waiting on file number I/O will awaken with SPT_ERROR and Guardian file-system error 16.

RETURN VALUES

SPT_SUCCESS

The specified filenum was successfully unregistered.

SPT_ERROR One of the following conditions exists:

The value specified for filenum s less than 0 (zero)

The specified filenum was not registered prior to this call

The FILE_COMPLETE_SET_ procedure removal of

filenum returned a nonzero value.

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

149

spt_unregOSSFileIOHandler(2) OSS System Calls Reference Manual

NAME

spt_unregOSSFileIOHandler - Unregisters an OSS file descriptor

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> extern spt_error_t spt_unregOSSFileIOHandler(

const int filedes);

PARAMETERS

filedes

Specifies the OSS file descriptor being unregistered

DESCRIPTION

This function unregisters an OSS file descriptor as one that the user manages.

RETURN VALUES

SPT_SUCCESS

The specified filedes was successfully unregistered.

SPT_ERROR The specified filedes is less than 0 (zero) or was not registered prior to this call.

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

150 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_unregPathsendTagHandler(2)

NAME

spt_unregPathsendTagHandler - Unregisters the user-supplied Pathsend tag

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> spt_error_t spt_unregPathsendTagHandler (

const long tag );

PARAMETERS

tag

Specifies the Pathsend tag to be unregistered.

DESCRIPTION

This function unregisters the specified Pathsend tag as a tag that user manages.

RETURN VALUES

SPT_SUCCESS

The specified tag was unregistered.

SPT_ERROR The specified tag was never registered.

RELATED INFORMATION

Functions: spt_regPathsendTagHandler(2), SPT_SERVERCLASS_DIALOG_ABORT_(2),

SPT_SERVERCLASS_DIALOG_BEGIN_(2), SPT_SERVERCLASS_DIALOG_END_(2),

SPT_SERVERCLASS_DIALOG_SEND_(2), SPT_SERVERCLASS_SEND_INFO_(2),

SPT_SERVERCLASS_SEND_(2).

STANDARDS CONFORMANCE

This function is an extension to the UNIX98 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

151

spt_usleep(2) OSS System Calls Reference Manual

NAME

spt_usleep - Suspends execution of the thread for a specified number of microseconds

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int spt_usleep (

unsigned int useconds );

PARAMETERS

useconds

Specifies the number of microseconds for which the thread is to be suspended. The value specified must be less than or equal to

1000000.

DESCRIPTION

The spt_usleep( ) function suspends a thread for a specified number of microseconds. A certain amount of delay can be expected in the processing of the spt_usleep( ) call because of other processor-intensive or input/output-intensive threads.

RETURN VALUES

The spt_usleep( ) function returns the value 0 (zero) when the call completes successfully. Otherwise, spt_usleep( ) returns -1 and sets errno.

ERRORS

If the following condition occurs, spt_usleep( ) sets errno to the corresponding value:

[EINTR]

[EINVAL]

A pthread_kill( ) function call received a signal that is not blocked, ignored, or handled.

The value specified for the useconds parameter was greater than

1000000.

RELATED INFORMATION

Functions: spt_sleep(2).

STANDARDS CONFORMANCE

This function is an extension to the UNIX98 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

152 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_vfprintf(2)

NAME

spt_vfprintf - Initiates thread-aware vfprintf( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int spt_vfprintf(

FILE *stream,

const char *format,

va_list printarg);

PARAMETERS

See the vfprintf(3) reference page either online or in the Open System Services Library Calls

Reference Manual.

DESCRIPTION

This is a thread-aware version of the vfprintf( ) function. The file descriptor underlying the stream must be nonblocking for this function to be thread-aware.

The following macro maps spt_vfprintf( ) to vfprintf( ) and has been defined in spthread.h:

#define vfprintf(stream, format, printarg) \ spt_vfprintf((stream), (format), (printarg))

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See vfprintf(3) reference page. The following also applies:

The value of errno is never set to [EAGAIN] or [EWOULDBLOCK].

If the file descriptor underlying stream becomes invalid (is closed by another thread), -1 is returned with an errno value of [EBADF].

If a signal is received via he *Lpthread_kill( ) function and is not blocked, ignored, or handled, -1 is returned with an errno value of

[EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

153

spt_vprintf(2) OSS System Calls Reference Manual

NAME

spt_vprintf - Initiates thread-aware vprintf( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> int spt_vprintf(

const char *format,

va_list printarg);

PARAMETERS

See the vprintf(3) reference page either online or in the Open System Services Library Calls

Reference manual.

DESCRIPTION

This is a thread-aware version of the vprintf( ) function. The file descriptor underlying standard output must be nonblocking for this function to be thread-aware.

The following macro maps spt_vprintf( ) to vprintf( ) and has been defined in spthread.h:

#define vprintf(format, printarg) spt_vprintf(format, printarg)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the vprintf(3) reference page. The following also applies:

The value of errno is never set to [EAGAIN] or [EWOULDBLOCK].

If the file descriptor underlying stdout becomes invalid (is closed by another thread), -1 is returned with an errno value of [EBADF].

If a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, -1 is returned with an errno value of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

154 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_waitpid(2)

NAME

spt_waitpid - Initiates thread-aware waitpid( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> pid_t spt_waitpid(

pid_t pid,

int *stat_loc,

int options);

PARAMETERS

See the waitpid(2) reference page.

DESCRIPTION

This is a thread-aware version of the waitpid( ) function. The socket must be nonblocking for this function to be thread-aware.

The following macro maps spt_waitpid( ) to waitpid( ) and has been defined in spthread.h:

#define waitpid(pid, stat_loc, options) \ spt_waitpid(pid, stat_loc, options)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the waitpid(2) reference page. Also, if a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, -1 is returned with an errno value of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

155

spt_wakeup(2) OSS System Calls Reference Manual

NAME

spt_wakeup - Wakes up a thread awaiting tagged I/O

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> extern spt_error_t spt_wakeup(

const short filenum,

const long tag,

const long count_transferred,

const long error);

PARAMETERS

filenum tag

Specifies the Guardian file number being waited on

Specifies the tag that is being awaited; the value -1 indicates all tags

count_transferred

Specifies byte transfer count of completed I/O

error

Specifies Guardian error number for IO

DESCRIPTION

This function wakes up a thread awaiting the tagged I/O on the file with the specified Guardian file number. The awakened thread returns from its call to the spt_awaitio( ) function with a return value of SPT_SUCCESS.

RETURN VALUES

SPT_SUCCESS

One of the following conditions exists:

tag was not -1 and waiting I/O was awakened. Note that only one awaiting I/O was awakened.

tag was -1 and awaiting I/O (if any) was awakened.

SPT_ERROR One of the following conditions exists:

The value specified for filenum was less than 0 (zero).

tag was not -1 and no awaiting IO was found.

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

156 Hewlett-Packard Company 527186-003

System Functions (s and S) spt_write(2)

NAME

spt_write - Initiates thread-aware write( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> ssize_t spt_write(

int filedes,

void *buffer,

size_t nbytes);

PARAMETERS

See the write(2) reference page.

DESCRIPTION

This is a thread-aware version of the write( ) function. The file descriptor must be nonblocking for this function to be thread-aware.

The following macro maps spt_write( ) to write( ) and has been defined in spthread.h:

#define write(filedes, buffer, nbytes)\ spt_write(filedes, buffer, nbytes)

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the write(2) reference page. The following also applies:

The value of errno is never set to [EWOULDBLOCK] or [EAGAIN].

If the file descriptor becomes invalid (is closed by another thread), -1 is returned with an errno value of [EBADF].

If a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, -1 is returned with an errno value of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

527186-003 Hewlett-Packard Company 7

157

spt_writev(2) OSS System Calls Reference Manual

NAME

spt_writev - Initiate thread-aware writev( ) function

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> ssize_t spt_writev(

int filedes,

struct iovec *iov,

int iov_count);

PARAMETERS

See the writev(2) reference page.

DESCRIPTION

This is a thread-aware version of the writev( ) function. The file descriptor must be nonblocking for this function to be thread-aware.

The following macro maps spt_writev( ) to writev( ) and has been defined in spthread.h:

#define writev(filedes, iov, iov_count) \ spt_writev((filedes), (iov), (iov_count))

This macro is available only when SPT_THREAD_AWARE has been defined before including

spthread.h, as follows:

#define SPT_THREAD_AWARE

RETURN VALUES

See the writev(2) reference page. The following also applies:

The value of errno is never set to [EWOULDBLOCK] or [EAGAIN].

If the file descriptor becomes invalid (is closed by another thread), -1 is returned with an errno value of [EBADF].

If a signal is received via the pthread_kill( ) function and is not blocked, ignored, or handled, -1 is returned with an errno value of [EINTR].

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification. Interfaces documented on this reference page conform to the following industry standards:

IEEE Std 1003.1c-1995, POSIX System Application Program Interface

The use of the header file spthread.h is an HP exception to the POSIX standard.

7

158 Hewlett-Packard Company 527186-003

System Functions (s and S) stat(2)

NAME

stat - Provides information about a file

LIBRARY

G-series native Guardian processes: system library

G-series native OSS processes: system library

H-series native Guardian processes: implicit libraries

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/types.h>

/* optional except for POSIX.1 */

#include <sys/stat.h> int stat(

const char *path,

struct stat *buffer);

PARAMETERS

path buffer

Points to the pathname identifying the file.

Points to a stat structure, into which information is placed about the file. The stat structure is described in the sys/stat.h header file.

DESCRIPTION

The stat( ) function obtains information about the file whose name is pointed to by the path parameter. Read, write, or execute permission for the named file is not required, but all directories listed in the pathname leading to the file must be searchable.

The file information is written to the area specified by the buffer parameter, which is a pointer to a stat structure with this definition from the sys/stat.h header file:

struct stat { dev_t st_dev; ino_t st_ino; mode_t st_mode; nlink_t st_nlink; char filler_1[2]; uid_t st_uid; gid_t st_gid; char filler_2[4]; dev_t st_rdev; off_t st_size; time_t st_atime; time_t st_mtime; time_t st_ctime; int64_t reserved[3];

};

For a regular file, the stat( ) function sets the st_size field of the stat structure to the length of the file and sets the st_mode field to indicate the file type. For a symbolic link, the stat( ) function returns information about the file at the end of the link; no information about the link is returned

(use the lstat( ) function for information about the link).

The stat( ) function updates any time-related fields associated with the file before writing into the

stat structure, unless it is a read-only fileset. Time-related fields are not updated for read-only

527186-003 Hewlett-Packard Company 7

159

stat(2) OSS System Calls Reference Manual

OSS filesets.

The fields in the stat structure have these meanings and content:

st_dev

OSS device identifier for a fileset.

Values for local OSS objects are listed next. Values for local

Guardian objects are described in Use on Guardian Objects, and values for remote Guardian or OSS objects are described in

Use on Remote Objects, later in this reference page.

st_ino

For Contains

Regular file

Directory

ID of device containing directory entry

ID of device containing directory

FIFO ID of special fileset for pipes

AF_UNIX socket ID of device containing the fileset in which the socket file was created

/dev/null

/dev/tty

ID of device containing directory entry

ID of device containing directory entry

File serial number (inode number). The file serial number and

OSS device identifier uniquely identify a regular OSS file within an OSS fileset.

Values for OSS objects are listed next. Values for Guardian objects are described in Use on Guardian Objects, later in this reference page.

st_mode

For Contains

Regular file

Directory

File serial number (unique)

File serial number (unique)

FIFO File serial number (unique)

AF_UNIX socket File serial number of the socket file

(unique)

/dev/null

/dev/tty

File serial number (unique)

File serial number (unique)

The st_ino value for all node entries in /E (including the entry for the logical link from the local node name to the root fileset on the local node) is the value for the root fileset on the corresponding node. If normal conventions are followed, this value is always 0 (zero), so entries in /E appear to be nonunique.

Values for objects on remote nodes are unique only among the values for objects within the same fileset on that node.

File mode. These bits are ORed into the st_mode field:

S_IFMT

File type. This field can contain one of these values:

S_IFCHR

Character special file.

7

160 Hewlett-Packard Company 527186-003

System Functions (s and S) stat(2)

S_IFDIR

S_IFIFO

S_IFREG

Directory.

FIFO.

Regular file.

S_IFSOCK

Socket.

For an AF_UNIX socket, the user permissions from the inode for the socket are returned for the permission bits. The access flags are also returned from the inode.

S_IRWXG

Group class

S_IRWXO

Other class

S_IRWXU

Owner class

S_ISGID

S_ISUID

S_ISVTX

Set group ID on execution

Set user ID on execution

Sticky bit; used only for directories (not ORed for files in /G, the Guardian file system)

S_NONSTOP Regular file in the OSS file system protected by disk process checkpointing. (Files in /G cannot have this bit set.)

When set, indicates that return from a write operation does not occur until both the primary and backup disk processes have the data

(thereby protecting the data against a single point of failure).

OSS file-system data caching is disabled for write operations on files for which this bit is set.

Performance is slower than when caching is used, but data integrity protection increases.

Performance is faster than when the O_SYNC bit in the open( ) function oflag parameter is used, but data integrity protection is less than that provided by O_SYNC use.

S_TRUST

Indicates that the file does not contain code for | an uncooperative process or code to examine or | modify I/O buffers. This flag suppresses operat| ing system protection of the buffers when the | memory segment containing the buffers is not shared. This flag applies only to loadfiles for a |

| process and can be set only by a user with appropriate privileges (the super ID).

|

527186-003 Hewlett-Packard Company 7

161

stat(2) OSS System Calls Reference Manual st_nlink st_uid st_gid

S_TRUSTSHARED

Indicates that the file does not contain code for | an uncooperative process or code to examine or | modify I/O buffers. This flag suppresses operat| ing system protection of the buffers regardless of whether the memory segment containing the |

| buffers is shared. This flag applies only to loadfiles for a process and can be set only by a |

| user with appropriate privileges (the super ID).

Values for Guardian objects are described in Use on Guardian

Objects, later in this reference page.

Number of links.

Values for OSS objects are listed next. Values for Guardian objects are described in Use on Guardian Objects, later in this reference page.

For Contains

Regular file

Directory

Number of links to the file

Number of links to the directory

FIFO Number of links to the file

AF_UNIX socket Number of links to the socket file

/dev/null

/dev/tty

Number of links to the file

Number of links to the file

User ID.

Values for OSS objects are listed next. Values for Guardian objects are described in Use on Guardian Objects, later in this reference page.

For Contains

Regular file

Directory

User ID of the file owner

User ID of the file owner

FIFO User ID of the file owner

AF_UNIX socket User ID of the creator of the socket file

/dev/null

/dev/tty

User ID of the super ID

User ID of the super ID

Group ID.

Values for OSS objects are listed next. Values for Guardian objects are described in Use on Guardian Objects, later in this reference page.

7

162 Hewlett-Packard Company 527186-003

System Functions (s and S) stat(2) st_rdev st_size st_atime

For Contains

Regular file

Directory

Group ID of the file group

Group ID of the file group

FIFO Group ID of the file group

AF_UNIX socket Group ID of the creator of the socket file

/dev/null

/dev/tty

Group ID of the super ID

Group ID of the super ID

Remote device ID.

Values for OSS objects are listed next. Values for Guardian objects are described in Use on Guardian Objects, later in this reference page.

For Contains

Regular file

Directory

Undefined

Undefined

FIFO Undefined

AF_UNIX socket 0 (zero)

/dev/null

/dev/tty

Undefined

ID of the device

File size.

Values for OSS objects are listed next. Values for Guardian objects are described in Use on Guardian Objects, later in this reference page.

For Contains

Regular file

Directory

FIFO

Size of the file in bytes

4096

0 (zero)

AF_UNIX socket 0 (zero)

/dev/null

0 (zero)

/dev/tty

0 (zero)

Access time.

Values for OSS objects are listed next. Values for Guardian objects are described in Use on Guardian Objects, later in this reference page.

527186-003 Hewlett-Packard Company 7

163

stat(2) OSS System Calls Reference Manual st_mtime st_ctime

For Contains

Regular file

Directory

Time of the last access

Time of the last access

FIFO Time of the last access

AF_UNIX socket Value retrieved from the inode

/dev/null

/dev/tty

Current time

Composite value of the times of all openers of the file

For the /E entry of the local node, the value is the time of the most recent mounting of the root fileset.

Modification time.

Values for OSS objects are listed next. Values for Guardian objects are described in Use on Guardian Objects, later in this reference page.

For Contains

Regular file

Directory

FIFO

Time of the last data modification

Time of the last modification

Time of the last data modification

AF_UNIX socket Value retrieved from the inode

/dev/null

Current time

/dev/tty

Composite value of the times of all openers of the file

For the /E entry of the local node, the value is the time of the most recent mounting of the root fileset.

Status change time.

Values for OSS objects are listed next. Values for Guardian objects are described in Use on Guardian Objects, later in this reference page.

For Contains

Regular file

Directory

Time of the last file status change

Time of the last file status change

FIFO Time of the last file status change

AF_UNIX socket Value retrieved from the inode

/dev/null

/dev/tty

Current time

Composite value of the times of all openers of the file

For the /E entry of the local node, the value is the time of the most recent mounting of the root fileset.

7

164 Hewlett-Packard Company 527186-003

System Functions (s and S) stat(2)

Use on Guardian Objects

The st_dev and st_ino fields of the stat structure do not uniquely identify Guardian files (files in

/G).

The st_dev field is unique for /G, for each disk volume and for each Telserv process (or other process of subdevice type 30), because each of these is a separate fileset.

The S_ISGUARDIANOBJECT macro can indicate whether an object is a Guardian object when the st_dev field is passed to the macro. The value of the macro is TRUE if the object is a

Guardian object and FALSE otherwise.

The st_ino field is a nonunique encoding of the Guardian filename.

The st_rdev field contains a unique minor device number for each ptyn entry in /G/ztnt/, representing each Telserv process subdevice.

The st_size field of an EDIT file (file code 101) is the actual (physical) end of file, not the number of bytes in the file. For directories, st_size is set to 4096.

When an OSS function is called for a Guardian EDIT file, the st_mtime field is set to the last modification time. The st_atime field indicates the last time the file was opened, and the

st_ctime field is set equal to st_mtime. No other time-related fields are updated by OSS function calls.

The st_ctime and st_atime fields for Guardian regular disk files (except for EDIT files) are updated by OSS function calls, not by Guardian procedure calls.

The time fields for /G, /G/vol, and /G/vol/subvol always contain the current time.

When the path parameter points to the name of a Guardian process that is not a process of subtype 30, the stat( ) function call fails. The value -1 is returned, and errno is set to [ENOENT].

The stat( ) function always returns access modes of "d---------" when the path parameter points to a Guardian subvolume that has a reserved name beginning with ZYQ. The other access modes reported for files in /G vary according to the file type.

The next table shows the mapping between Guardian files and their corresponding file types described in the st_mode field.

Table 7

1. Guardian File Type Mappings

Example in /G

Guardian

File Type st_mode

File Type Permissions

/G

vol

N/A

Disk volume

vol/subvol Subvolume

vol/subvol/fileid Disk file

vol/#123

ztnt ztnt/#pty0001 vol1/zyq00001

Temporary disk file

Subtype 30 process

Subtype 30 process with qualifier

Subvolume

Directory

Directory

Directory

Regular file

Regular file

Directory r-xr-xr-x rwxrwxrwx rwxrwxrwx

See following text

Character special rw-rw-rw-

Directory

See following text

--x--x--x

---------

A Guardian file classified as a directory is always owned by the super ID.

527186-003 Hewlett-Packard Company 7

165

stat(2) OSS System Calls Reference Manual

Guardian permissions are mapped as listed:

A Guardian network or any user permission is mapped to an OSS other permission.

A Guardian community or group user permission is mapped to an OSS group permission.

A Guardian user or owner permission is mapped to an OSS owner permission.

A Guardian super ID permission is an OSS super ID permission.

Guardian read permission is mapped to OSS read permission.

Guardian write permission is mapped to OSS write permission.

Guardian execute permission is mapped to OSS execute permission.

Guardian purge permission is ignored.

Users are not allowed read access to Guardian processes.

OSS file permissions are divided into three groups (owner, group, and other) of three permission bits each (read, write, and execute). Note that the OSS permission bits do not distinguish between remote and local users as Guardian security does; local and remote users are treated alike.

Use on Remote Objects

The content of the st_dev field of the stat structure is unique for each node in /E because each of these is a separate fileset. Values for directories within /E are the same as described for objects on the local HP NonStop node.

The S_ISEXPANDOBJECT macro can indicate whether an object in the /E directory is on a remote HP NonStop node when the st_dev field is passed to the macro. The value of the macro is TRUE if the object is on a remote HP NonStop node and FALSE otherwise.

Use From the Guardian Environment

The stat( ) function belongs to a set of functions that have these effects when the first of them is called from the Guardian environment:

Two Guardian file system file numbers (not necessarily the next two available) are allocated for the root directory and the current working directory. These file numbers cannot be closed by calling the Guardian

FILE_CLOSE_ procedure.

The current working directory is assigned from the VOLUME attribute of the Guardian environment =_DEFAULTS DEFINE.

The use of static memory by the process increases slightly.

These effects occur only when the first of the set of functions is called. The effects are not cumulative.

RETURN VALUES

Upon successful completion, the value 0 (zero) is returned. Otherwise, the value -1 is returned, and errno is set to indicate the error.

7

166 Hewlett-Packard Company 527186-003

System Functions (s and S) stat(2)

ERRORS

If any of these conditions occurs, the stat( ) function sets errno to the corresponding value:

[EACCES]

[EFAULT]

[EFSBAD]

[EIO]

Search permission is denied for a component of the pathname pointed to by the path parameter.

Either the buffer parameter or the path parameter points to a location outside of the allocated address space of the process.

The program attempted an operation involving a fileset with a corrupted fileset catalog.

An input or output error occurred. The device holding the file might be in the down state, or both processors that provide access to the device might have failed.

[ELOOP] Too many symbolic links were encountered in translating path.

[ENAMETOOLONG]

One of these is too long:

The pathname pointed to by the path parameter

A component of the pathname pointed to by the path parameter

The intermediate result of pathname resolution when a symbolic link is part of the path parameter

The pathconf( ) function can be called to obtain the applicable limits.

[ENOENT] One of these conditions exists:

The file specified by the path parameter does not exist.

The path parameter points to an empty string.

The specified pathname cannot be mapped to a valid

Guardian filename.

The specified pathname points to the name of a Guardian process that is not of subtype 30.

The path parameter specifies a file on a remote HP Non-

Stop node, but communication with the remote node has been lost.

[ENOROOT] One of these conditions exists:

The root fileset of the local node (fileset 0) is not in the

STARTED state.

The current root fileset for the specified file is unavailable. The OSS name server for the fileset might have failed.

The specified file is on a remote HP NonStop node, and communication with the remote name server has been lost.

527186-003 Hewlett-Packard Company 7

167

stat(2) OSS System Calls Reference Manual

[ENOTDIR] A component of the pathname specified by the path parameter is not a directory.

[ENXIO] An invalid device or address was specified during an input or output operation on a special file. One of these events occurred:

A device was specified that does not exist, or a request was made beyond the limits of the device.

The fileset containing the requestor’s current working directory or root directory is not mounted. This error can occur after failure and restart of an OSS name server process until the fileset has been repaired and remounted.

[EOSSNOTRUNNING]

The program attempted an operation on an object in the OSS environment while a required system process was not running.

For all other error conditions, errno is set to the appropriate Guardian filesystem error number. See the Guardian Procedure Errors and Messages

Manual for more information about a specific Guardian file-system error.

RELATED INFORMATION

Functions: chmod(2), chown(2), link(2), lstat(2), mknod(2), open(2), pipe(2), utime(2).

STANDARDS CONFORMANCE

The POSIX standards leave some features to the implementing vendor to define. These features are affected in the HP implementation:

For files other than regular disk files or symbolic links, the st_size field of the stat structure is set to 0 (zero). For directories, st_size is set to

4096.

The S_IRWXU, S_IRWXG, S_IRWXO, S_IFMT, S_ISVTX,

S_NONSTOP, S_ISGID, and S_ISUID bits are ORed into the st_mode field of the stat structure.

The stat( ) function does not return the errno value [EOVERFLOW].

HP extensions to the XPG4 Version 2 specification are:

The errno values [EFAULT], [EFSBAD], [ENOROOT], [ENXIO], and

[EOSSNOTRUNNING] can be returned by the stat( ) function.

7

168 Hewlett-Packard Company 527186-003

System Functions (s and S) statvfs(2)

NAME

statvfs - Gets fileset information using a pathname

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/statvfs.h> int statvfs(

const char *path,

struct statvfs *buffer);

PARAMETERS

path buffer

Is a pathname that specifies any file within a mounted fileset.

Points to a statvfs structure that is to hold the returned information for the statvfs( ) call.

DESCRIPTION

The statvfs( ) function returns descriptive information about a mounted fileset. The information is returned in a statvfs structure, which has the following definition from the sys/statvfs.h header file:

typedef struct statvfs { unsigned long unsigned long unsigned long unsigned long unsigned long unsigned long unsigned long unsigned long unsigned long char unsigned long unsigned long char unsigned long unsigned long unsigned long

} statvfs_t; f_bsize; f_frsize; f_blocks; f_bfree; f_bavail; f_files; f_ffree; f_favail; f_fsid; f_basetype[FSTYPSZ]; f_flag; f_namemax; f_fstr[32]; f_bminavail; f_bmaxavail; f_filler[5];

The fields in this structure have the following meanings and content:

f_bsize

Fileset block size.

527186-003 Hewlett-Packard Company 7

169

statvfs(2) OSS System Calls Reference Manual f_frsize f_blocks

For

Regular file

Directory

FIFO

AF_UNIX socket

/dev/null

Object in /G

/G

/G/ztnt/#ptynn

/E

Fundamental file system block size.

Contains

4096

4096

4096

4096

4096

4096

4096

4096

4096

For

Regular file

Directory

FIFO

AF_UNIX socket

/dev/null

Object in /G

/G

/G/ztnt/#ptynn

/E

Contains

4096

4096

4096

4096

4096

4096

4096

4096

4096

Total number of blocks in fileset, in units of f_frsize.

For

Regular file

Directory

FIFO

AF_UNIX socket

/dev/null

Object in /G

/G

/G/ztnt/#ptynn

/E

Contains

Number of blocks on all volumes ever used in the fileset.

Number of blocks on all volumes ever used in the fileset.

Number of blocks on all volumes ever used in the fileset.

Number of blocks on all volumes ever used in the fileset.

0

0

Number of blocks on all volumes ever used in the fileset.

Number of blocks on the volume containing the object.

0

7

170 Hewlett-Packard Company 527186-003

System Functions (s and S) statvfs(2) f_bfree f_bavail

Total number of free blocks in fileset.

For

Regular file

Directory

FIFO

AF_UNIX socket

/dev/null

Object in /G

Contains

0

0

0

Number of free blocks on all volumes currently in the storage-pool file for the fileset.

Number of free blocks on all volumes currently in the storage-pool file for the fileset.

Number of free blocks on all volumes currently in the storage-pool file for the fileset.

Number of free blocks on all volumes currently in the storage-pool file for the fileset.

Number of free blocks on all volumes currently in the storage-pool file for the fileset.

Number of free blocks in the volume containing the object.

/G

/G/ztnt/#ptynn

/E

Number of free blocks available to a process without appropriate privileges.

For

Regular file

Directory

FIFO

AF_UNIX socket

/dev/null

Object in /G

/G

Contains

Number of free blocks on all volumes currently in the storage-pool file for the fileset.

Number of free blocks on all volumes currently in the storage-pool file for the fileset.

Number of free blocks on all volumes currently in the storage-pool file for the fileset.

Number of free blocks on all volumes currently in the storage-pool file for the fileset.

Number of free blocks on all volumes currently in the storage-pool file for the fileset.

Number of free blocks in the volume containing the object.

0

527186-003 Hewlett-Packard Company 7

171

statvfs(2) OSS System Calls Reference Manual f_files f_ffree f_favail

/G/ztnt/#ptynn

/E

0

0

Total number of file serial numbers (inode numbers) in the fileset.

For

Regular file

Directory

FIFO

AF_UNIX socket

/dev/null

Object in /G

/G

/G/ztnt/#ptynn

/E

Contains

Number of inode numbers in the fileset.

Number of inode numbers in the fileset.

Number of inode numbers in the fileset.

Number of inode numbers in the fileset.

0

0

Number of inode numbers in the fileset.

The value of ULONG_MAX.

0

Total number of free file serial numbers (inode numbers) in the fileset.

For

Regular file

Directory

FIFO

AF_UNIX socket

/dev/null

Contains

The value of ULONG_MAX.

0

0

0

Number of free inode numbers in the fileset.

Number of free inode numbers in the fileset.

Number of free inode numbers in the fileset.

Number of free inode numbers in the fileset.

Number of free inode numbers in the fileset.

Object in /G

/G

/G/ztnt/#ptynn

/E

Number of file serial numbers (inode numbers) available to a process without appropriate privileges.

7

172 Hewlett-Packard Company 527186-003

System Functions (s and S) f_fsid

For

Regular file

Directory

FIFO

AF_UNIX socket

/dev/null

Object in /G

/G

/G/ztnt/#ptynn

/E

Fileset identifier.

For

Regular file

Directory

FIFO

AF_UNIX socket

/dev/null

Object in /G

/G

/G/ztnt/#ptynn

/E f_basetype

Type of file system.

statvfs(2)

Contains

Number of free inode numbers in the fileset.

Number of free inode numbers in the fileset.

Number of free inode numbers in the fileset.

Number of free inode numbers in the fileset.

0

0

0

Number of free inode numbers in the fileset.

The value of ULONG_MAX.

Contains

Lower 32 bits of the st_dev field in the stat structure.

Lower 32 bits of the st_dev field in the stat structure.

Lower 32 bits of the st_dev field in the stat structure.

Lower 32 bits of the st_dev field in the stat structure.

Lower 32 bits of the st_dev field in the stat structure.

Lower 32 bits of the st_dev field in the stat structure.

Lower 32 bits of the st_dev field in the stat structure.

Lower 32 bits of the st_dev field in the stat structure.

Lower 32 bits of the st_dev field in the stat structure.

527186-003 Hewlett-Packard Company 7

173

statvfs(2) OSS System Calls Reference Manual f_flag

For

Regular file

Directory

FIFO

AF_UNIX socket

/dev/null

Object in /G

/G

/G/ztnt/#ptynn

/E

Contains

OSS

OSS

OSS

OSS

OSS

GUARDIAN

GUARDIAN

GUARDIAN

EXPAND

Bit mask indicating type of fileset access allowed.

For

Regular file

Directory

FIFO

AF_UNIX socket

/dev/null

Contains

2

3

2

3

4 if fileset is read/write, 5 if fileset is readonly.

4 if fileset is read/write, 5 if fileset is readonly.

4 if fileset is read/write, 5 if fileset is readonly.

4 if fileset is read/write, 5 if fileset is readonly.

4 if fileset is read/write, 5 if fileset is readonly.

Object in /G

/G

/G/ztnt/#ptynn

/E

The content of the f_flag field can be tested with the following symbolic values:

ST_NOSUID

This bit flag is set if the fileset does not allow the setuid bit to be set for its member files.

ST_NOTRUNC

This bit flag is set if the fileset does not truncate filenames.

ST_RDONLY This bit flag is set if the fileset is mounted for read-only access.

7

174 Hewlett-Packard Company 527186-003

System Functions (s and S) statvfs(2) f_namemax

Maximum number of character bytes in a filename within the fileset.

f_fstr

For

Regular file

Directory

FIFO

AF_UNIX socket

/dev/null

Object in /G

/G

/G/ztnt/#ptynn

/E

Fileset pathname prefix string.

Contains

248

248

248

248

7

7

7

248

8

For

Regular file

Directory

FIFO

AF_UNIX socket

/dev/null

Object in /G

/G

/G/ztnt/#ptynn

/E

Contains

/E/nodename/G/volume/ZXnnnnnn n, identifying the catalog file and version for the specified file.

/E/nodename/G/volume/ZXnnnnnn n, identifying the catalog file and version for the specified file.

/E/nodename/G/volume/ZXnnnnnn n, identifying the catalog file and version for the specified file.

/E/nodename/G/volume/ZXnnnnnn n, identifying the catalog file and version for the specified file.

/E/nodename/G/volume/ZXnnnnnn n, identifying the catalog file and version for the specified file.

/E/nodename/G/volume, identifying the disk volume containing the specified file.

/E/nodename/G

/E/nodename/G

/E f_bminavail

Number of blocks free on the disk volume with the least space remaining.

527186-003 Hewlett-Packard Company 7

175

statvfs(2) OSS System Calls Reference Manual

For

Regular file

Directory

FIFO

AF_UNIX socket

/dev/null

Object in /G

/G

/G/ztnt/#ptynn

/E

Contains

Number of blocks.

Number of blocks.

Number of blocks.

Number of blocks.

0

0

0

Number of blocks.

Number of blocks.

f_bmaxavail

Number of blocks free on the disk volume with the most space remaining.

For

Regular file

Directory

FIFO

AF_UNIX socket

/dev/null

Object in /G

/G

/G/ztnt/#ptynn

/E

Contains

0

0

Number of blocks.

Number of blocks.

Number of blocks.

Number of blocks.

Number of blocks.

Number of blocks.

0

Use From the Guardian Environment

The statvfs( ) function is one of a set of functions that have the following effects when the first of them is called from the Guardian environment:

Two Guardian file system file numbers (not necessarily the next two available) are allocated for the root directory and the current working directory. These file numbers cannot be closed by calling the Guardian

FILE_CLOSE_ procedure.

The current working directory is assigned from the VOLUME attribute of the Guardian environment =_DEFAULTS DEFINE.

The use of static memory by the process increases slightly.

These effects occur only when the first of the set of functions is called. The effects are not cumulative.

NOTES

This function provides compatibility with the System V Interface Definition, Revision 3.

RETURN VALUES

Upon successful completion, the statvfs( ) function returns the value 0 (zero). Otherwise, it returns the value -1 and errno is set to indicate the error.

7

176 Hewlett-Packard Company 527186-003

System Functions (s and S) statvfs(2)

ERRORS

If any of the following conditions occurs, the statvfs( ) function sets errno to the corresponding value:

[EACCES]

[EFAULT]

[EINTR]

[EIO]

Search permission is denied for a component of the path prefix of the path parameter.

The buffer or path parameter points to a location outside of the allocated address space of the process.

The function was interrupted by a signal before any data arrived.

One of the following conditions occurred:

The process is a member of a background process group attempting to write to its controlling terminal, the TOS-

TOP flag is set, the process is neither ignoring nor blocking the SIGTTOU signal, and the process group of the process is orphaned.

A physical I/O error has occurred. The device holding the file might be in the down state, or both processors that provide access to the device might have failed.

Data might have been lost during a transfer.

[ELOOP] Too many symbolic links were encountered in translating the

path parameter.

[ENAMETOOLONG]

One of the following is too long:

The pathname pointed to by the path parameter

A component of the pathname pointed to by the path parameter

The intermediate result of pathname resolution when a symbolic link is part of the path parameter

The pathconf( ) function can be called to obtain the applicable limits.

[ENOENT] The file referred to by the path parameter does not exist.

[ENOTDIR] A component of the path prefix of the path parameter is not a directory.

RELATED INFORMATION

Functions: fstat(2), fstatvfs(2), lstat(2), stat(2).

527186-003 Hewlett-Packard Company 7

177

symlink(2) OSS System Calls Reference Manual

NAME

symlink - Creates a symbolic link to a file

LIBRARY

G-series native Guardian processes: system library

G-series native OSS processes: system library

H-series native Guardian processes: implicit libraries

H-series OSS processes: implicit libraries

SYNOPSIS

#include <unistd.h> int symlink(

const char *path1,

const char *path2);

PARAMETERS

path1 path2

Specifies the file for which the symbolic link must be created.

The file named by the path1 parameter does not need to exist when the link is created. The path1 parameter can refer to a symbolic link.

Names the symbolic link to be created. An error is returned if the symbolic link named by the path2 parameter already exists.

DESCRIPTION

The symlink( ) function creates a symbolic link with the name specified by the path2 parameter, which refers to the file named by the path1 parameter.

Like a hard link (described in the link(2) reference page), a symbolic link allows a file to have multiple names. The presence of a hard link guarantees the existence of a file, even after the original name has been removed; a symbolic link provides no such guarantee. Unlike hard links, a symbolic link can cross fileset boundaries.

When a component of a pathname refers to a symbolic link rather than a directory, the pathname contained in the symbolic link is resolved. If the pathname in the symbolic link starts with a slash (/) character, the symbolic link pathname is resolved relative to the root directory of the process. If the pathname in the symbolic link does not start with a slash (/) character, the symbolic link pathname is resolved relative to the directory that contains the symbolic link.

If the symbolic link is not the last component of the original pathname, the remaining components of the original pathname are appended to the contents of the link and pathname resolution continues.

The symbolic link pathname may or may not be traversed, depending on which function is being performed. Most functions traverse the link.

The functions that refer only to the symbolic link itself, rather than to the object to which the link refers, are as follows:

link( ) lstat( )

An error is returned if a symbolic link is named by the path2 parameter.

If the file specified is a symbolic link, the status of the link itself is returned.

7

178 Hewlett-Packard Company 527186-003

System Functions (s and S) symlink(2) mknod( ) open( ) readlink( ) remove( ) rename( ) rmdir( ) unlink( )

An error is returned if a symbolic link is named as the path parameter.

An error is returned when O_CREAT and O_EXCL are both specified and the path parameter specifies an existing symbolic link.

This function applies only to symbolic links.

A symbolic link can be removed by invoking the remove( ) function.

If the file to be renamed is a symbolic link, the symbolic link is renamed. If the new name refers to an existing symbolic link, the symbolic link is destroyed.

An error is returned if a symbolic link is named as the path parameter.

A symbolic link can be removed by invoking unlink( ).

Execute (search) permission for the directories within a symbolic link are required to traverse the resolved pathname. Normal permission checks are made on each component of the symbolic link pathname during its resolution.

Use on Guardian Objects

The symlink( ) function can be used to create a symbolic link between an OSS fileset and an object in the Guardian file system (/G). Symbolic links cannot be created in /G.

Use From the Guardian Environment

The symlink( ) function can be used by a Guardian process when the process has been compiled using the #define _XOPEN_SOURCE_EXTENDED 1 feature-test macro or an equivalent compiler command option.

The symlink( ) function is one of a set of functions that have the following effects when the first of them is called from the Guardian environment:

Two Guardian file-system file numbers (not necessarily the next two available) are allocated for the root directory and the current working directory. These file numbers cannot be closed by calling the Guardian

FILE_CLOSE_ procedure.

The current working directory is assigned from the VOLUME attribute of the Guardian environment =_DEFAULTS DEFINE.

The use of static memory by the process increases slightly.

These effects occur only when the first of the set of functions is called. The effects are not cumulative.

NOTES

An absolute pathname that includes a symbolic link for an OSS file on a remote HP NonStop node is expanded relative to the root fileset of the remote node. For example, if path1 is specified as /usr/bin and path2 is specified as link, then a reference to /E/node1/link is expanded to

/E/node1/usr/bin and identifies the /usr/bin directory on the HP NonStop node named NODE1.

527186-003 Hewlett-Packard Company 7

179

symlink(2) OSS System Calls Reference Manual

RETURN VALUES

Upon successful completion, the symlink( ) function returns the value 0 (zero). Otherwise, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the symlink( ) function sets errno to the corresponding value:

[EACCES] One of the following conditions exists:

The requested operation requires writing in a directory with a mode that denies write permission.

Search permission is denied on a component of path2.

[EEXIST]

[EFAULT]

[EFSBAD]

The path specified by the path2 parameter already exists.

Either the path1 or the path2 parameter points outside the process’s allocated address space.

The fileset catalog for one of the filesets involved in the operation is corrupt.

[EIO]

[ELOOP]

An input/output error occurred during a read from or write to the fileset.

Too many symbolic links were found in translating path2.

[ENAMETOOLONG]

One of the following is too long:

The pathname pointed to by the path1 or path2 parameter

A component of the pathname pointed to by the path1 or

path2 parameter

The intermediate result of pathname resolution when a symbolic link is part of the pathname pointed to by the

path2 parameter

The pathconf( ) function can be called to obtain the applicable limits.

[ENOENT] One of the following conditions exists:

A named directory does not exist.

A specified pathname is an empty string.

A specified pathname cannot be mapped to a valid Guardian filename.

The path1 or path2 parameter specifies a file on a remote HP NonStop node but communication with the remote node has been lost.

7

180 Hewlett-Packard Company 527186-003

System Functions (s and S) symlink(2)

[ENOROOT] One of the following conditions exists:

The root fileset of the local node (fileset 0) is not in the

STARTED state.

The current root fileset for the specified file is unavailable. The OSS name server for the fileset might have failed.

The specified file is on a remote HP NonStop node and communication with the remote name server has been lost.

[ENOSPC] The directory in which the entry for the symbolic link is being placed cannot be extended because there is no space left on the fileset containing the directory, or the new symbolic link cannot be created because there is no space left on the fileset that contains the link.

[ENOTDIR] A component of path2 is not a directory.

[ENOTSUP] The fileset pointed to by the path1 parameter cannot support symbolic links. This error is returned for files in /G and for files in D3x-series filesets.

[ENXIO] The fileset containing the client’s working directory or effective root directory is not mounted.

[EOSSNOTRUNNING]

The program attempted an operation on an object in the OSS environment while a required system process was not running.

[EROFS] The requested operation requires writing in a directory on a read-only fileset.

RELATED INFORMATION

Functions: link(2), lstat(2), mknod(2), readlink(2), remove(3), rename(2), rmdir(2), stat(2),

unlink(2).

Commands: ln(1).

STANDARDS CONFORMANCE

The following are HP extensions to the XPG4 Version 2 specification:

The errno values [EFAULT], [EFSBAD], [ENOROOT], [ENOTSUP],

[ENXIO], and [EOSSNOTRUNNING] can be returned.

527186-003 Hewlett-Packard Company 7

181

SPT_ABORTTRANSACTION(3) OSS System Calls Reference Manual

NAME

SPT_ABORTTRANSACTION - Aborts and backs out a transaction associated with the current process and current thread

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> signed16 SPT_ABORTTRANSACTION( void

);

PARAMETERS

None.

DESCRIPTION

This function aborts and backs out a transaction associated with the current process and the current thread.

RETURN VALUES

A status word is returned. The value is one of the following:

0 (zero) The SPT_ABORTTRANSACTION( ) operation completed successfully.

Nonzero values

The Guardian file-system error with this error number occurred.

RELATED INFORMATION

Functions: SPT_ENDTRANSACTION(3).

7

182 Hewlett-Packard Company 527186-003

System Functions (s and S) SPT_BEGINTRANSACTION(3)

NAME

SPT_BEGINTRANSACTION - Starts a new transaction associated with the current process and current thread

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> signed16 SPT_BEGINTRANSACTION(

signed32 *trans-begin-tag

);

PARAMETERS

Output

trans_begin_tag

Returns a value that identifies the new transaction among other transaction identifiers that the calling process has begun

DESCRIPTION

This function begins a new transaction associated with the current process and the current thread.

RETURN VALUES

A status word is returned. The value is one of the following:

0 (zero) The SPT_BEGINTRANSACTION( ) operation completed successfully.

Nonzero values

The Guardian file-system error with this error number occurred.

RELATED INFORMATION

Functions: SPT_ENDTRANSACTION(3).

527186-003 Hewlett-Packard Company 7

183

SPT_ENDTRANSACTION(3) OSS System Calls Reference Manual

NAME

SPT_ENDTRANSACTION - Ends the transaction associated with the current process and current thread

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> signed16 SPT_ENDTRANSACTION( void

);

PARAMETERS

None.

DESCRIPTION

This function commits the database changes associated with a transaction started by the current thread; if the action finishes successfully, the changes made by the transaction are permanent and the locks held for the transaction are released.

SPT_ENDTRANSACTION( ) is a thread-synchronous operation. For example, the thread (but not the process), will wait for completion of the operation. The operation is, therefore, a thread cancellation point. In other words, a cancel exception can be delivered while the thread is waiting for ENDTRANSACTION completion. If such a cancellation occurs, the ENDTRANSAC-

TION might or might not have finished. The TMF STATUSTRANSACTION procedure call can be used to determine the state.

RETURN VALUES

A status word is returned. The value is one of the following:

0 (zero) The SPT_ENDTRANSACTION( ) operation completed successfully.

Nonzero values

The Guardian file-system error with this error number occurred.

RELATED INFORMATION

Functions: SPT_BEGINTRANSACTION(3).

7

184 Hewlett-Packard Company 527186-003

System Functions (s and S) SPT_RESUMETRANSACTION(3)

NAME

SPT_RESUMETRANSACTION - Restores a transaction associated with the current process and current thread

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> signed16 SPT_RESUMETRANSACTION(

signed32 trans-begin-tag

);

PARAMETERS

Input

trans_begin_tag

This is the value returned for this transaction by the trans-begin-tag parameter of

SPT_BEGINTRANSACTION( ). A value of 0 (zero) indicates that there is no current transaction.

DESCRIPTION

This function restores a transaction associated with the current process and the current thread. It can also be used to suspend the current thread’s association with a transaction.

RETURN VALUES

A status word is returned. The value is one of the following:

0 (zero) The SPT_RESUMETRANSACTION( ) operation completed successfully.

Nonzero values

The Guardian file-system error with this error number occurred.

RELATED INFORMATION

Functions: SPT_BEGINTRANSACTION(3).

527186-003 Hewlett-Packard Company 7

185

SPT_SERVERCLASS_DIALOG_ABORT_(3) OSS System Calls Reference Manual

NAME

SPT_SERVERCLASS_DIALOG_ABORT_ - Aborts the specified dialog

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> signed16 SPT_SERVERCLASS_DIALOG_ABORT_(

signed32 dialogId,

);

PARAMETERS

Input

dialogId

Contains the identifier returned from

SPT_SERVERCLASS_DIALOG_BEGIN_( ) that specifies the dialog for this abort operation.

DESCRIPTION

This function is used to abort the specified dialog. The parameters and semantics of this function are the same as those of the Guardian SERVERCLASS_DIALOG_ABORT_ procedure, which is described in the NonStop TS/MP Pathsend and Server Programming Manual.

RETURN VALUES

Possible return values are the following Guardian file-system error numbers:

0 (zero) The SPT_SERVERCLASS_DIALOG_ABORT_( ) operation completed successfully.

233 (FEScError)

You can call the SPT_SERVERCLASS_SEND_INFO_( ) function to get detailed information about this error.

ERRORS

This function does not set errno.

RELATED INFORMATION

Functions: SPT_SERVERCLASS_DIALOG_BEGIN_(3),

SPT_SERVERCLASS_DIALOG_END_(3), SPT_SERVERCLASS_DIALOG_SEND_(3),

SPT_SERVERCLASS_SEND_INFO_(3).

7

186 Hewlett-Packard Company 527186-003

System Functions (s and S) SPT_SERVERCLASS_DIALOG_BEGIN_(3)

NAME

SPT_SERVERCLASS_DIALOG_BEGIN_ - Initiates the dialog and also sends the first message of the dialog to the server instance in the Pathway serverclass

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> signed16 SPT_SERVERCLASS_DIALOG_BEGIN_(

signed32 *dialogId,

char * pathmon_process_name,

signed16 pathmon_process_name_len,

char * server_class_name,

signed16 server_class_name_len,

void * message_buffer,

signed16 request_len,

signed16 maximum_reply_len,

[signed16 *actual_reply_len,]

[signed32 timeout,]

[unsigned16 flags,]

[signed16 *sc_send_opnum,]

[signed32 tag]

);

PARAMETERS

Input

pathmon_process_name

Contains the external process name of the PATHMON process controlling the server class (for example, $PM or \AB.$PM).

pathmon_process_name_len

Contains the character length of pathmon_process_name.

server_class_name

Contains the name of the server class to send to.

server_class_name_len

Contains the character length of server_class_name.

message_buffer

Contains the message to send to the server class.

request_len

Contains the byte length of the data contained in message_buffer.

maximum_reply_len

Contains the maximum number of bytes that are expected in the reply message from the server class.

timeout

(Optional) Contains the maximum amount of time, in hundredths of a second, that LINKMON waits for the completion of this send. This value must be either

-1 or greater than 0 (zero). The default value is -1 (wait indefinitely).

If the begin is still in progess when this timeout expires, then the begin is canceled. An error value of 233 (FEScError) is returned;

SPT_SERVERCLASS_SEND_INFO_( ) reports Pathsend error 918 (FEScSendOperationAborted) and Guardian file-system error 40.

527186-003 Hewlett-Packard Company 7

187

SPT_SERVERCLASS_DIALOG_BEGIN_(3) OSS System Calls Reference Manual

flags tag

(Optional) If specified, this parameter must contain 0 (zero) for a single TMF transaction per dialog or 2 for multiple TMF transactions per dialog. This flag value (0 or 2) also indicates that this operation is always waited. This parameter is provided for compatibility with the Guardian

SERVERCLASS_DIALOG_BEGIN_ procedure.

(Optional) If specified, this parameter is ignored. This parameter is provided for compatibility with the Guardian SERVERCLASS_DIALOG_BEGIN_ procedure.

Output

dialogId

Contains the identifier returned on successful completion of this call that can be used on subsequent operations on this dialog.

message_buffer

On successful completion of the send, contains the reply returned by the server process.

actual_reply_len

(Optional) If specified, returns the number of bytes returned in the server process reply and stored in the area pointed to by message_buffer.

scsend_op_num

(Optional) If specified, returns the value -1. This parameter is provided only for compatibility with the Guardian SERVERCLASS_DIALOG_BEGIN_ procedure.

DESCRIPTION

This function is used to initiate the dialog and send the first message of the dialog to the server instance in the Pathway serverclass. The parameters and semantics of this function are the same as those of the Guardian SERVERCLASS_DIALOG_BEGIN_ procedure, which is described in the NonStop TS/MP Pathsend and Server Programming Manual.

This function differs from the Guardian SERVERCLASS_DIALOG_BEGIN_ procedure in that it provides only a waited (to the thread) interface. Three optional parameters (flags, scsend-op-

num, and tag) are used to specify nowait operations. These parameters should usually be omitted.

The flags parameter, if provided, must be 0 (zero) or 2. If a value other than zero or two is provided, the operation fails with an error value of 233 (FEScError).

STP_SERVERCLASS_SEND_INFO_( ) reports Pathsend error 909 (FEScInvalid-FlagsValue) and file-system error 29 (FEInvalOp).

The thread is suspended for the duration of the begin operation. Other threads in the process are scheduled to run. The timeout parameter can be used to specify that the send be canceled after a specified interval. Alternatively, the pthread_cancel( ) function can be used (by another thread) to cancel the begin operation in progress in a thread. The cancel exception generated by

pthread_cancel( ) can be subsequently handled by the thread. As with the CANCEL and

SERVERCLASS_DIALOG_BEGIN_ Guardian procedures, the program cannot determine whether the canceled message was sent or canceled before the server process finished processing the request. If the begin is canceled because of expiration of the timeout parameter, then the function returns with an error value of 233 (FEScError);

SPT_SERVERCLASS_SEND_INFO_( ) reports Pathsend error 918 (FEScSend-

OperationAborted) and Guardian file-system error 40.

7

188 Hewlett-Packard Company 527186-003

System Functions (s and S) SPT_SERVERCLASS_DIALOG_BEGIN_(3)

NOTES

The message_buffer parameter should refer to static or heap-allocated storage. It should not be automatic storage and should not be stack-allocated storage for a TNS process. If stack-allocated storage for a TNS process is specified, an error value 233 (FEScError) is returned;

SPT_SERVERCLASS_SEND_INFO_( ) reports Pathsend error 912 (FEScParameterBoundsError).

The message buffer is modified by the server reply. Therefore, the same buffer area should not be used concurrently by more than one thread. The threads package does not check for this condition; it is the responsibility of the programmer who is using threads.

Multiple SPT_SERVERCLASS_DIALOG_BEGIN_( ) operations can be in progress in different threads within a process. The maximum number of concurrent calls is determined by the number of threads and the Pathsend limit of 512 for each LINKMON.

RETURN VALUES

Possible return values are the following Guardian file-system error numbers:

0 (zero) The SPT_SERVERCLASS_DIALOG_BEGIN_( ) operation completed successfully.

70 (FEContinue)

The server is ready for the next message in the dialog.

233 (FEScError)

You can call the SPT_SERVERCLASS_SEND_INFO_( ) function to get detailed information about this error.

ERRORS

This function does not set errno.

RELATED INFORMATION

Functions: SPT_SERVERCLASS_DIALOG_ABORT_(3),

SPT_SERVERCLASS_DIALOG_END_(3), SPT_SERVERCLASS_DIALOG_SEND_(3),

SPT_SERVERCLASS_SEND_INFO_(3).

527186-003 Hewlett-Packard Company 7

189

SPT_SERVERCLASS_DIALOG_END_(3) OSS System Calls Reference Manual

NAME

SPT_SERVERCLASS_DIALOG_END_ - Cleans up resources for the specified dialog after the server has ended it

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> signed16 SPT_SERVERCLASS_DIALOG_END_(

signed32 dialogId,

);

PARAMETERS

Input

dialogId

Contains the identifier returned from

SPT_SERVERCLASS_DIALOG_BEGIN_( ) that specifies the dialog for this end operation.

DESCRIPTION

This function is used to clean up resources for the specified dialog after the server has ended it.

The parameters and semantics of this function are the same as those of the Guardian

SERVERCLASS_DIALOG_END_ procedure, which is described in the NonStop TS/MP Path-

send and Server Programming Manual.

RETURN VALUES

Possible return values are the following Guardian file-system error numbers:

0 (zero) The SPT_SERVERCLASS_DIALOG_END_( ) operation completed successfully.

233 (FEScError)

You can call the SPT_SERVERCLASS_SEND_INFO_( ) function to get detailed information about this error.

ERRORS

This function does not set errno.

RELATED INFORMATION

Functions: SPT_SERVERCLASS_DIALOG_ABORT_(3),

SPT_SERVERCLASS_DIALOG_BEGIN_(3), SPT_SERVERCLASS_DIALOG_SEND_(3),

SPT_SERVERCLASS_SEND_INFO_(3).

7

190 Hewlett-Packard Company 527186-003

System Functions (s and S) SPT_SERVERCLASS_DIALOG_SEND_(3)

NAME

SPT_SERVERCLASS_DIALOG_SEND_ - Initiates a send within the specified dialog to the server instance in the Pathway serverclass

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> signed16 SPT_SERVERCLASS_DIALOG_SEND_(

signed32 dialogId,

void * message_buffer,

signed16 request_len,

signed16 maximum_reply_len,

[signed16 *actual_reply_len,]

[signed32 timeout,]

[unsigned16 flags,]

[signed16 *sc_send_opnum,]

[signed32 tag]

);

PARAMETERS

Input

dialogId

Contains the identifier returned from a call to the

SPT_SERVERCLASS_DIALOG_BEGIN_( ) function that specifies the dialog for this send operation.

message_buffer

Contains the message to send to the server class.

request_len

Contains the byte length of the data contained in message_buffer.

maximum_reply_len

Contains the maximum number of bytes that are expected in the reply message from the server class.

timeout

(Optional) Contains the maximum amount of time, in hundredths of a second, that LINKMON waits for the completion of this send. This value must be either

-1 or greater than 0 (zero). The default value is -1 (wait indefinitely).

If the send is still in progress when this timeout expires, then the send is canceled. An error value 233 (FEScError) is returned;

SPT_SERVERCLASS_SEND_INFO_( ) reports Pathsend error 918 (FEScSendOperationAborted) and Guardian file-system error 40.

flags

(Optional) If specified, must contain 0 (zero) to indicate a waited operation. This parameter is provided for compatibility with the Guardian

SERVERCLASS_DIALOG_SEND_ procedure.

tag

(Optional) If specified, this parameter is ignored. This parameter is provided for compatibility with the Guardian SERVERCLASS_DIALOG_SEND_ procedure.

527186-003 Hewlett-Packard Company 7

191

SPT_SERVERCLASS_DIALOG_SEND_(3) OSS System Calls Reference Manual

Output

message_buffer

On successful completion of the send, contains the reply returned by the server process.

actual_reply_len

(Optional) If provided, returns the number of bytes returned in the server process reply and stored in the area pointed to by message_buffer.

scsend_op_num

(Optional) If provided, returns the value -1. This parameter is provided only for compatibility with the Guardian SPT_SERVERCLASS_DIALOG_SEND_ procedure.

DESCRIPTION

This function is used to send a message within the specified dialog to the server instance in the

Pathway serverclass. The parameters and semantics of this function are the same as those of the

Guardian SERVERCLASS_DIALOG_SEND_ procedure, which is described in the NonStop

TS/MP Pathsend and Server Programming Manual.

This function differs from the Guardian SERVERCLASS_DIALOG_SEND_ procedure in that it provides only a waited (to the thread) interface. Three optional parameters (flags, scsend-op-

num, and tag) are used to specify nowait operations. These parameters should usually be omitted.

The flags parameter, if provided, must be 0 (zero). If a value other than zero is provided, the operation fails with an error value of 233 (FEScError).

SPT_SERVERCLASS_SEND_INFO_( ) reports Pathsend error 909 (FEScInvalid-FlagsValue) and file-system error 29 (FEInvalOp).

The thread is suspended for the duration of the send operation. Other threads in the process are scheduled to run. The timeout parameter can be used to specify that the send be canceled after a specified interval. Alternatively, the pthread_cancel( ) function can be used (by another thread) to cancel the send operation in progress in a thread. The cancel exception generated by

pthread_cancel( ) can be subsequently handled by the thread. As with the CANCEL and

SERVERCLASS_DIALOG_SEND_ Guardian procedures, the program cannot determine whether the canceled message was sent or canceled before the server process finished processing the request. If the send is canceled because of expiration of the timeout parameter, then the function returns with an error value of 233 (FEScError); SPT_SERVERCLASS_SEND_INFO_( ) reports Pathsend error 918 (FEScSend-OperationAborted) and Guardian file-system error 40.

NOTES

The message_buffer parameter should refer to static or heap-allocated storage. It should not be automatic storage and should not be stack-allocated storage for a TNS process. If stack-allocated storage for a TNS process is specified, an error value 233 (FEScError) is returned;

SPT_SERVERCLASS_SEND_INFO_( ) reports Pathsend error 912 (FEScParameterBoundsError).

The message buffer is modified by the server reply. Therefore, the same buffer area should not be used concurrently by more than one thread. The threads package does not check for this condition; it is the responsibility of the programmer who is using threads.

Multiple SPT_SERVERCLASS_DIALOG_SEND_( ) operations can be in progress in different threads within a process. The maximum number of concurrent calls is determined by the number of threads and the Pathsend limit of 512 for each LINKMON.

7

192 Hewlett-Packard Company 527186-003

System Functions (s and S) SPT_SERVERCLASS_DIALOG_SEND_(3)

RETURN VALUES

Possible return values are the following Guardian file-system error numbers:

0 (zero) The SPT_SERVERCLASS_SEND_( ) operation completed successfully.

70 (FEContinue)

The server is ready for the next message in the dialog.

233 (FEScError)

You can call the SPT_SERVERCLASS_SEND_INFO_( ) function to get detailed information about this error.

ERRORS

This function does not set errno.

RELATED INFORMATION

Functions: SPT_SERVERCLASS_DIALOG_ABORT_(3),

SPT_SERVERCLASS_DIALOG_BEGIN_(3), SPT_SERVERCLASS_DIALOG_END_(3),

SPT_SERVERCLASS_SEND_INFO_(3).

527186-003 Hewlett-Packard Company 7

193

SPT_SERVERCLASS_SEND_(3) OSS System Calls Reference Manual

NAME

SPT_SERVERCLASS_SEND_ - Sends a message to and receives a reply from a server process in a Pathway server class

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> signed16 SPT_SERVERCLASS_SEND_(

char * pathmon_process_name,

signed16 pathmon_process_name_len,

char * server_class_name,

signed16 server_class_name_len,

void * message_buffer,

signed16 request_len,

signed16 maximum_reply_len,

[signed16 *actual_reply_len],

[signed32 timeout],

[unsigned16 flags],

[signed16 *sc_send_opnum],

[signed32 tag]

);

PARAMETERS

Input

pathmon_process_name

Contains the external process name of the PATHMON process controlling the server class (for example, $PM or \AB.$PM).

pathmon_process_name_len

Contains the character length of pathmon_process_name.

server_class_name

Contains the name of the server class to send to.

server_class_name_len

Contains the character length of server_class_name.

message_buffer

Contains the message to send to the server class.

request_len

Contains the byte length of the data contained in message_buffer.

maximum_reply_len

Contains the maximum number of bytes that are expected in the reply message from the server class.

timeout

(Optional) Contains the maximum amount of time, in hundredths of a second,

LINKMON waits for the completion of this send. This value must be either -1 or greater than 0 (zero). The default value is -1 (wait indefinitely).

If the send is still in progess when this timeout expires, then the send is canceled.

An error value 233 (FEScError) is returned;

SPT_SERVERCLASS_SEND_INFO_() will show Pathsend error 918

(FEScSendOperationAborted) and Guardian file-system error 40.

7

194 Hewlett-Packard Company 527186-003

System Functions (s and S) SPT_SERVERCLASS_SEND_(3)

flags tag

(Optional) If provided, must contain 0 (zero) to indicate a waited operation.

This parameter is provided for compatibility with the Guardian

SERVERCLASS_SEND_ procedure.

(Optional) If provided, is ignored. This parameter is provided for compatibility with the Guardian SERVERCLASS_SEND_ procedure.

Output

message_buffer

On successful completion of the send, contains the reply returned by the server process.

actual_reply_len

(Optional) If provided, returns the number of bytes returned in the server process reply and stored in the area pointed to by message_buffer.

scsend_op_num

(Optional) If provided, returns the value -1. This parameter is provided only for compatibility with the Guardian SERVERCLASS_SEND_ procedure.

DESCRIPTION

This function is used to send a message to and receive a reply message from a server process in a

Pathway server class. The parameters and semantics of this function are the same as those of the

Guardian SERVERCLASS_SEND_ procedure, which is described in the NonStop TS/MP Path-

send and Server Programming Manual.

This function differs from the Guardian SERVERCLASS_SEND_ procedure in that it provides only a waited (to the thread) interface. Three optional parameters (flags, scsend-op-num, and

tag) are used to specify nowait operations. These parameters should usually be omitted.

The flags parameter, if provided, must be 0 (zero). If a value other than zero is provided, the operation fails with an error value of 233 (FEScError).

STP_SERVERCLASS_SEND_INFO_( ) will show Pathsend error 909 (FEScInvalid-

FlagsValue).

The thread is suspended for the duration of the send operation. Other threads in the process are scheduled to run. The timeout parameter can be used to specify that the send be canceled after a specified interval. Alternatively, pthread_cancel( ) can be used (by another thread) to cancel the send operation in progress in a thread. The cancel exception generated by pthread_cancel( ) can be subsequently handled by the thread. As with the CANCEL and SERVERCLASS_SEND_

Guardian procedures, the program cannot determine whether the canceled message was sent or canceled before the server process finished processing the request. If the send is canceled because of expiration of the timeout parameter, then the function returns with an error value of

233 (FEScError); SPT_SERVERCLASS_SEND_INFO_( ) will show Pathsend error 918

(FEScSend-OperationAborted) and Guardian file-system error 40.

The message_buffer parameter should refer to static or heap-allocated storage. It should not be automatic storage and should not be stack-allocated storage for a TNS process. If stack-allocated storage for a TNS process is specified, an error value 233 (FEScError) is returned;

SPT_SERVERCLASS_SEND_INFO_( ) will show Pathsend error 912 (FEScParameter-

BoundsError).

The message buffer is modified by the server reply. Therefore, the same buffer area should not be used concurrently by more than one thread. The threads package does not check for this condition; it is the responsibility of the programmer who is using threads.

Multiple SPT_SERVERCLASS_SEND_( ) operations can be in progress in different threads within a process. The maximum number of concurrent calls is determined by the number of threads and the Pathsend limit of 512 for each LINKMON.

527186-003 Hewlett-Packard Company 7

195

SPT_SERVERCLASS_SEND_(3) OSS System Calls Reference Manual

If SPT_SERVERCLASS_SEND_( ) is called while the thread has a current transaction, the transaction identifier is propagated to the server class process. If the send is to a server class configured with the TMF parameter OFF, then the send finishes with return error 233 (FEScEr-

ror) and SPT_SERVERCLASS_SEND_INFO_( ) will show Pathsend error 917 (FEScServer-

ClassTmfViolation) and Guardian file-system error 0.

RETURN VALUES

Possible return values are the following Guardian file-system error numbers:

0 (zero) The SPT_SERVERCLASS_SEND_( ) operation completed successfully.

233 (FEScError)

You can call the SPT_SERVERCLASS_SEND_INFO_( ) function to get detailed information about this error.

RELATED INFORMATION

Functions: SPT_SERVERCLASS_SEND_INFO_(3).

7

196 Hewlett-Packard Company 527186-003

System Functions (s and S) SPT_SERVERCLASS_SEND_INFO_(3)

NAME

SPT_SERVERCLASS_SEND_INFO_ - Returns information about the last server-class send operation

LIBRARY

G-series native OSS processes: /G/system/sysnn/zsptsrl

H-series OSS processes: /G/system/zdllnnn/zsptdll

SYNOPSIS

#include <spthread.h> signed16 SPT_SERVERCLASS_SEND_INFO_(

[signed16 *Pathsend_error,]

);

[signed16 *file_system_error]

PARAMETERS

Output

Pathsend_error

(Optional) Returns the Pathsend error number. See the information about Pathsend error handling in the NonStop TS/MP Pathsend and Server Programming

Manual for descriptions of Pathsend errors.

file_system_error

(Optional) Returns the Guardian file-system error number.

DESCRIPTION

This function is used to retrieve information about the last SPT_SERVERCLASS_SEND_( ) operation performed by the current thread. The parameters and semantics of this routine are the same as those of the Guardian SERVERCLASS_SEND_INFO_ procedure, which is described in the NonStop TS/MP Pathsend and Server Programming Manual. The difference is that this function returns the information for the last message attempted or sent by the thread rather than by the process.

A call to SPT_SERVERCLASS_SEND_INFO_( ) by a thread that has never called

SPT_SERVERCLASS_SEND_( ) results in the return of error value 0, Pathsend error 906

(FEScNoSendEverCalled), and Guardian file-system error 0.

RETURN VALUES

If an error value is returned, the error is associated with the call to

SPT_SERVERCLASS_SEND_INFO_( ) and not the SPT_SERVERCLASS_SEND_( ) operation. The value is one of the following Guardian file-system error numbers:

The SPT_SERVERCLASS_SEND_INFO_( ) operation completed successfully.

The user has an invalid segment in use.

A parameter address is out of bounds.

RELATED INFORMATION

Functions: SPT_SERVERCLASS_SEND_(3).

527186-003 Hewlett-Packard Company 7

197

Section 8. System Functions (t)

This section contains reference pages for Open System Services (OSS) system function calls with names that begin with t. These reference pages reside in the cat2 directory and are sorted alphabetically by U.S. English conventions in this section.

527186-003 Hewlett-Packard Company 8

1

tdm_execve(2) OSS System Calls Reference Manual

NAME

tdm_execve - Executes a file with HP extensions

LIBRARY

G-series native OSS processes: /G/system/sysnn/zossksrl

H-series OSS processes: /G/system/zdllnnn/zosskdll

SYNOPSIS

#include <tdmext.h>

[ extern char **environ; ]

int tdm_execve( const char

∗∗

path,

char

∗∗

const argv[ ],

char

∗∗

const envp[ ],

const struct process_extension

∗∗

pe_parms,

struct process_extension_results

∗∗

pr_results);

PARAMETERS

**environ

path

argv[ ]

envp[ ]

pe_parms pr_results

Points to an array of character pointers to environment strings. The environment strings define the OSS environment for the calling process. The environ array is terminated by a null pointer.

Points to a null-terminated string containing a pathname that identifies the new process image file. The pathname is absolute if it starts with a slash (/) character.

Otherwise, the pathname is relative and is resolved by prefixing the current working directory.

Specifies an array of character pointers to null-terminated strings containing arguments to be passed to the main function of the new program. argv[0] should point to the null-terminated string containing the filename of the new process image. The last member of this array must be a null pointer.

Specifies an array of character pointers to null-terminated strings that describe the environment for the new process.

Points to the input structure containing Guardian process attributes to be assigned to the new process. The structure must be defined locally to match the definition in the tdmext.h header file. The local structure must be initialized before its first use. Initialization can be done by using the #define

DEFAULT_PROCESS_EXTENSION, as defined in the tdmext.h header file.

The initialized values can then be modified as appropriate for the call. When this parameter contains a null pointer, the tdm_execve( ) function assumes default Guardian attributes.

Points to the output structure containing optional process identification and error information. In case of error, this structure provides additional information including the PROCESS_LAUNCH_ procedure error and error detail. The structure must be defined locally to match the definition in the tdmext.h header file.

The local structure must be initialized before its first use. Initialization can be done using the #define DEFAULT_PROCESS_EXTENSION_RESULTS, as defined in the tdmext.h header file.

See the process_extension_results(5) reference page for information about the | content of the structure. The tdmext.h header file is not kept current when new | error codes are defined for process creation functions. The list of _TPC_ macros | described in that reference page is not complete; for a current description of error |

|

8

2 Hewlett-Packard Company 527186-003

System Functions (t) tdm_execve(2)

macros and error codes, see the Guardian header file

$SYSTEM.ZSPIDEF.ZGRDC or the summary of process-creation errors in the |

|

Guardian Procedure Calls Reference Manual (see the table entitled "Summary | of Process Creation Errors").

DESCRIPTION

The tdm_execve( ) function replaces the current process image with a new process image. The new image is constructed from a regular executable file, called a new process image file. The new process image file is formatted as an executable text or binary file in one of the formats recognized by the tdm_execve( ) function.

The tdm_execve( ) function is similar to the tdm_execvep( ) function. The main difference is the way the pathname for the process image file is resolved. tdm_execve( ) always resolves relative pathnames by using the current working directory; see Identifying the Process Image File, later in this reference page. tdm_execvep( ) sometimes uses the PATH environment variable to resolve pathnames.

A successful tdm_execve( ) function call does not return, because the calling process image is overlaid by the new process image.

When a program is executed as a result of a tdm_execve( ) call, it is entered as a function call:

int main(

int argc,

char

∗∗

argv[ ],

char

∗∗

envp);

Here, the argc parameter is the argument count, the argv[ ] parameter is an array of character pointers to the arguments themselves, and the envp parameter is a pointer to a character array listing the environment variables. The argv[ ] array is terminated by a null pointer. The null pointer is not counted in argc.

The arguments specified by a program using the tdm_execve( ) function are passed on to the new process image in the corresponding arguments to the main( ) function.

Use From the Guardian Environment

If called from a Guardian process, the actions of this function are undefined, and errno is set to

[ENOTOSS].

Identifying the Process Image File

The tdm_execve( ) function uses the path parameter to identify the process image file. This parameter points to the absolute pathname if the pathname starts with a slash (/) character. Otherwise, the pathname is relative and is resolved by prefixing the current working directory.

Passing the Arguments

The argv[ ] parameter is an array of character pointers to null-terminated strings. The last member of this array is a null pointer. These strings constitute the argument list available to the new process image. The value in argv[0] should point to a filename that is associated with the process being started by the tdm_execve( ) function.

Specifying the Environment

The envp[ ] parameter is an array of character pointers to null-terminated strings. These strings constitute the environment for the new process image. The environment array is terminated with a null pointer.

The number of bytes available for the new process’s combined argument and environment lists has a system-imposed limit. This limit, which includes the pointers and the null terminators on the strings, is available by calling the sysconf(_SC_ARG_MAX) function.

527186-003 Hewlett-Packard Company 8

3

tdm_execve(2) OSS System Calls Reference Manual

Executing a Binary File

If the file specified as the new process image file is a binary executable file, the tdm_execve( ) function loads the file directly.

Executing a Text File

If the file specified as the new process image file is not a binary executable file, the

tdm_execve( ) function examines the file to determine whether it is an executable text file. It checks for a header line in this format:

#! interpreter_name [optional_string]

The #! notation identifies the file as an executable text file. The new process image filename is constructed from the process image filename in the interpreter_name string, treating it like the

path parameter. The Guardian input and output structures pointed to by the pe_parms and

pr_results parameters apply to the command interpreter as they would to any process file.

The arguments passed to the new process are modified as listed:

argv[0] is set to the name of the command interpreter.

If the optional_string portion is present, argv[1] is set to optional_string.

The next element of argv[ ] is set to the original value of path.

The remaining elements of argv[ ] are set to the original elements of argv[ ], starting with

argv[1]. The original argv[0] is discarded.

The S_ISUID and S_ISGID mode bits of an executable text file are honored. Those bits are ignored for the interpreter_name command interpreter.

When the File Is Invalid

If the process image file is not a valid executable object, or if the text file does not contain the header line, the tdm_execve( ) function returns and sets errno to [ENOEXEC].

Open Files

File descriptors open in the calling process image remain open in the new process image, except for those:

Whose close-on-exec flag FD_CLOEXEC is set (see the fcntl(2) reference page)

Opened using a Guardian function or procedure call

For a G-series TNS process image or an accelerated process image only, if the process file segment (PFS) of the new process image is smaller than the process file segment of the calling process image and if the calling process image has a large number of file descriptors open, the system might not be able to propagate all the open file descriptors to the new process image. When this situation occurs, the function call fails, and errno is set to the value of [EMFILE].

For those file descriptors that remain open, all attributes of the open file descriptor, including file locks, remain unchanged. All directory streams are closed.

Open Pipes and FIFOs

A pipe or FIFO associated with an open file descriptor in the calling process remains connected in the new process. If the new process runs in a different processor than the calling process, the processor that runs the new process must also be running an OSS pipe server process.

If no OSS pipe server process is running in the new processor, the new process cannot use the pipe or FIFO; calls specifying the file descriptor for the pipe or FIFO fail with errno set to

[EWRONGID]. The new process can only close the invalid file descriptor.

8

4 Hewlett-Packard Company 527186-003

System Functions (t) tdm_execve(2)

Existing Sockets

A socket associated with an open file descriptor in the calling process remains connected in the new process when the new process runs in the same processor as the calling process.

When the new process runs in a different processor than the calling process, the processor that runs the new process must also be running a socket transport agent process. If no socket transport agent process is running in the new processor, the new process cannot use the socket; calls specifying the file descriptor for the socket fail with errno set to [EWRONGID]. The new process can only close the invalid file descriptor.

Shared Memory

Any attached shared memory segments are detached from the new process by a successful call to the tdm_execve( ) function. See the shmat(2) reference page for additional information about shared memory segment use.

Semaphores

Semaphore set IDs attached to a calling process are also attached to the new process if the new process executes in the same processor as the calling process. The new process also inherits the adjust-on-exit (semadj) values of the calling process if both processes are in the same processor.

A semaphore set cannot be shared when a semadj value exists for the calling process and the new process is created in a different processor. When that condition exists, a call to the

tdm_execve( ) function fails, and errno is set to [EHLDSEM].

See the semget(2) reference page for additional information about semaphore use.

Signals

Signals set to:

The default action (SIG_DFL) in the calling process image are set to the default action in the new process image.

Be ignored (SIG_IGN) by the calling process image are set to be ignored by the new process image.

Cause abnormal termination (SIG_ABORT) in the calling process image are set to that | action in the new process image.

Cause entry into the debugger (SIG_DEBUG) in the calling process image are set to that | action in the new process image.

Be caught by the calling process image are set to the default action in the new process image.

See the signal(4) reference page either online or in the Open System Services System Calls Refer- |

ence Manual.

User ID and Group ID

If the set-user-ID mode bit (S_ISUID) of the new process image file is set (see the chmod(2) reference page), the effective user ID of the new process image is set to the user ID of the owner of the new process image file. Similarly, if the set-group-ID mode bit (S_ISGID) of the new process image file is set, the effective group ID of the new process image is set to the group ID of the new process image file. The real user ID, real group ID, and supplementary group IDs of the new process image remain the same as those of the calling process image. The effective user ID and effective group ID of the new process image are saved (as the saved-set user ID and the saved-set group ID) for use by the setuid( ) function.

527186-003 Hewlett-Packard Company 8

5

tdm_execve(2) OSS System Calls Reference Manual

OSS Attributes

These OSS attributes of the calling process image are unchanged after successful completion of the tdm_execve( ) function:

OSS process ID (PID)

Parent OSS process ID

Process group ID

Session membership

Real user ID

Real group ID

Supplementary group IDs

The time left until an alarm clock signal is posted (see the alarm(3) reference page)

Current working directory

Root directory

File mode creation mask (see the umask(2) reference page)

Process signal mask (see the sigprocmask(2) reference page)

Pending signals (see the sigpending(2) reference page)

The tms_utime, tms_stime, tms_cutime, and tms_cstime fields of the tms structure

File size limit (see the ulimit(2) reference page)

Upon successful completion, the tdm_execve( ) function marks the st_atime field of the file for update.

The POSIX.1 standard does not specify the effect on the st_atime field when the tdm_execve( ) function call fails but does find the file. Neither does the HP implementation guarantee the outcome. Under these circumstances, this field should not be used for further processing.

Default Guardian Attributes

If the pe_parms parameter contains a null pointer, the newly created OSS process retains all these default Guardian attributes of the process that calls the tdm_execve( ) function:

Priority

Processor on which the process executes

Home terminal

Job ID

DEFINE mode switch

Process access ID (PAID), unless the S_ISUID mode bit of the new process image file is set

8

6 Hewlett-Packard Company 527186-003

System Functions (t) tdm_execve(2)

Security group list

Job ancestor or GMOM

Unread system message index (PCBMCNT)

This attribute assignment is different from the assignment made when creating a new process with Guardian procedures.

Outstanding incoming and outgoing message limits

This attribute assignment is different from the assignment made when creating a new process with Guardian procedures.

Login, remote login, and saveabend flags

File creation mask

If the pe_parms parameter contains a null pointer, the default Guardian attributes of the new process that differ from those of the calling process are:

The program file is the file specified in the tdm_execve( ) call.

The library file is specified in the program file.

The process name for the new process is system-generated if the RUNNAMED option is set in the program file. Otherwise the process is unnamed.

The size of the data segment of the new process is set in the program file.

The remote login flag (PCBREMID) is set to zero (off) if the program file has its

S_ISUID mode bit set. Otherwise, the remote login flag is set the same as for the caller.

The size of the extended data segment of the new process is set in the program file.

The DEFINEs inherited by the new process depend on the setting of DEFINE mode in the caller. If DEFINE mode in the caller is ON, all the caller’s DEFINEs are inherited. If

DEFINE mode is OFF, no DEFINEs are inherited.

The new process does not inherit the extended swap file (if any) of the calling process.

For a G-series TNS process or an accelerated process, the extended data segment is managed by the Kernel Managed Storage Facility (KMSF) unless an extended swap file is specified in the pe_extswap_file_name field of the process_extension structure described elsewhere in this reference page.

The process identification number (PIN) of the new process is unrelated to that of the calling process. Usually, the PIN of the new process is unrestricted. However, the PIN can be restricted to the range 0 through 254 under the following conditions:

— The HIGHPIN flag is not set in, or is absent from, the program file or any library file.

_TPC_HIGHPIN_OFF is specified in the pe_create_options field of the

process_extension structure, described elsewhere in this reference page.

— The restriction is inherited. See _TPC_IGNORE_FORCEPIN_ATTR in the

pe_create_options field of the process_extension structure, described elsewhere in this reference page, for more information about controlling inheritance.

527186-003 Hewlett-Packard Company 8

7

tdm_execve(2) OSS System Calls Reference Manual

The creator access ID (CAID) is set to the process access ID (PAID) of the calling process.

The PAID depends on whether the S_ISUID mode bit of the process image file is set. If that bit is set, the PAID is based on the file owner ID. If not, the PAID is the same as for the caller. (The S_ISUID mode bit of the image file has no effect on the security group list.)

The MOM field for the new process depends on whether the calling process is named. If it is named, the MOM field of the new process is set to the caller’s ANCESTOR field.

Otherwise, the MOM field of the new process is set to the caller’s MOM field.

System debugger selection for the new process is based on INSPECT mode.

Code breakpoints and memory breakpoints are not inherited.

For detailed information about Guardian process attributes, see the PROCESS_LAUNCH_ procedure in the Guardian Procedure Calls Reference Manual.

Setting Guardian Attributes

The input structure pointed to by the pe_parms parameter permits the setting of Guardian attributes for the new process.

First, the input structure must be initialized to the default values (see Default Guardian Attri-

butes, earlier in this reference page) using the #define DEFAULT_PROCESS_EXTENSION.

After the structure is initialized, the values can be set using literals that are defined in the

tdmext.h header file.

If any optional parameter specified in the structure pointed to by pe_parms is not passed, the new process assumes the corresponding default value.

The input structure is defined in the tdmext.h header file. This structure contains fields that can vary from release version update (RVU) to RVU, including reserved and filler fields.

8

8 Hewlett-Packard Company 527186-003

System Functions (t) tdm_execve(2)

In the current RVU, these fields are meaningful:

typedef struct process_extension { long pe_len; char *pe_library_name; char *pe_swap_file_name; char *pe_extswap_file_name; short pe_priority; short pe_cpu; short pe_name_options; char filler_1[2]; char *pe_process_name; char *pe_hometerm; short pe_memory_pages; short pe_jobid; short pe_create_options; char filler_2[2]; char *pe_defines; short pe_defines_len; short pe_debug_options; long pe_pfs_size; short pe_OSS_options; char filler_3[2]; long pe_mainstack_max; long pe_heap_max; long pe_space_guarantee;

} process_extension_def;

The input structure passes this information:

pe_len

Specifies the size of the structure in bytes. This value is set by #define

DEFAULT_PROCESS_EXTENSION and should not be changed.

pe_library_name

Points to the name of the user library to be bound to the new process. The string that is pointed to is null-terminated and in OSS name format. If the pointer points to a zero-length string (a NULL character), the new process runs with no user library. An equivalent call to the Guardian PROCESS_LAUNCH_ procedure does this by setting the library filename length to -1.

This field is used only for G-series TNS or accelerated new process image files.

If a value is specified for this field for native object files, the specified value is ignored.

pe_swap_file_name

Points to a null-terminated string specifying the name of a file in the Guardian file system to be used as the swap file for the stack segment. For example, if the

Guardian filename is $A.B.C, the name used is /G/a/b/c.

This file cannot have the same name as that of a file used in a preceding call to the tdm_fork( ) function.

This field is not used in the current RVU of Open System Services. It exists for compatibility with older RVUs. Any specified value is checked for validity but otherwise ignored.

527186-003 Hewlett-Packard Company 8

9

tdm_execve(2) OSS System Calls Reference Manual pe_extswap_file_name

Points to a null-terminated string specifying the name of a disk file in the Guardian file system to be used as the swap file for the extended data segment. For example, if the Guardian filename is $A.B.D, the name used is /G/a/b/d.

This file cannot have the same name as that of a file used in a preceding call to the tdm_fork( ) function.

This field is used only for G-series TNS or accelerated new process image files.

If a value is specified for this field for native object files, the specified value is checked for validity but otherwise ignored.

By default, the new process uses KMSF to manage its extended swap segment.

HP recommends using the default.

pe_priority

Specifies the priority of the new process.

pe_cpu

Specifies the processor on which the new process will execute. The OSS process

ID (PID) of the process remains unchanged. This field is used to distribute system load.

pe_name_options

Specifies process naming as:

_TPC_GENERATE_NAME

The system generates the name.

_TPC_NAME_SUPPLIED

The process name is indicated by the pe_process_name field.

_TPC_NO_NAME

The new process is unnamed.

pe_process_name

Points to the null-terminated Guardian process name if

_TPC_NAME_SUPPLIED is specified in the pe_name_options field. For example, if the Guardian process name is $DELM, the name used is /G/delm.

pe_hometerm Points to the null-terminated name in the Guardian file system for the home terminal. For example, if the Guardian name is $ztnt.#xyz, the name used is

/G/ztnt/#xyz.

pe_memory_pages

Specifies the size of the data stack in 2 KB units. This field is used only for Gseries TNS or accelerated new process image files. If a value is specified for this field for native object files, the specified value is checked for validity but otherwise ignored.

pe_jobid

Specifies the job ID of the new process.

pe_create_options

Specifies process creation options as:

_TPC_BOTH_DEFINES

Propagates the current DEFINEs and the DEFINEs indicated in the input structure.

8

10 Hewlett-Packard Company 527186-003

System Functions (t) tdm_execve(2) pe_defines

_TPC_ENABLE_DEFINES

Enables DEFINEs when set if

_TPC_OVERRIDE_DEFMODE is also set. Disables

DEFINEs when not set.

_TPC_HIGHPIN_OFF

Restricts the new process to a PIN in the range 0 through 254.

This restriction is rarely useful for an OSS process; it allows obsolescent Guardian interfaces to interact with the process.

By default, this restriction is inherited by any child or successor process. The default can be overridden by using the

_TPC_IGNORE_FORCEPIN_ATTR field.

_TPC_IGNORE_FORCEPIN_ATTR

Ignores the _TPC_HIGHPIN_OFF restriction specified for or inherited by the caller or parent process. When

_TPC_IGNORE_FORCEPIN_ATTR is specified, the resulting process has a restricted PIN only if _TPC_HIGHPIN_OFF is also specified or if the object file for the program or a user library lacks the HIGHPIN attribute.

_TPC_OVERRIDE_DEFMODE

Specifies that the DEFINE mode of the new process is to be set according to the _TPC_ENABLE_DEFINES option rather than to the caller’s current DEFINE mode.

_TPC_PROCESS_DEFINES_ONLY

Propagates only the current set of DEFINEs.

_TPC_SUPPLIED_DEFINES_ONLY

Propagates only the DEFINEs indicated by the pe_defines field.

Points to a specified saved set of DEFINEs created by using the Guardian

DEFINESAVE procedure. These DEFINEs are propagated to the new process if either _TPC_SUPPLIED_DEFINES_ONLY or _TPC_BOTH_DEFINES is specified in the pe_create_options field.

Note: This string is not null-terminated.

pe_defines_len

Specifies the length of the string in the pe_defines field.

pe_debug_options

Provides control over the selection between the default and symbolic debuggers and over the creation of the saveabend file. A saveabend file can be examined by using the symbolic debugger to determine the cause of the abnormal termination.

In addition, you can use this option to force the new process to enter the default debugger before executing. Possible options are:

_TPC_CODEFILE_INSPECT_SAVEABEND

Uses the saveabend and INSPECT mode flags in the program file.

_TPC_DEBUG_NOSAVE

Uses the default debugger but does not create a saveabend file.

527186-003 Hewlett-Packard Company 8

11

tdm_execve(2) OSS System Calls Reference Manual

8

12

_TPC_DEBUG_SAVEABEND

Uses the default debugger and creates a saveabend file.

_TPC_ENTER_DEBUG

Starts the new process in the default debugging utility.

_TPC_INSPECT_NOSAVE

Uses the symbolic debugger but does not create a saveabend file.

_TPC_INSPECT_SAVEABEND

Uses the symbolic debugger and creates a saveabend file.

pe_pfs_size

Specifies the size of the PFS for the new process (this field is ignored).

pe_OSS_options

Specifies OSS options. No special action on signals is the default and only current OSS option.

pe_mainstack_max

Specifies the maximum size of the main stack in bytes for the new process.

If the calling process specifies a value, the value must be less than 32 MB. If the calling process does not specify a value or specifies a 0 (zero) value, the value specified in the object file of the new process is used. If no value is specified in the object file, the default value of 1 MB (for TNS/R systems) or 2 MB (for

TNS/E systems) is used.

pe_heap_max Specifies the maximum size of the heap in bytes for the new process if it is a native process.

See the C/C++ Programmer’s Guide description of the HEAP pragma for guidance on the use of nonzero values for this field.

If a value is specified for this field for G-series TNS or accelerated object files, the specified value is ignored.

pe_space_guarantee

Specifies the minimum available swap space to guarantee for the new process.

If the calling process specifies a value, the value must be less than or equal to a multiple of the page size of the processor in which the new process will run.

Values less than a multiple of the page size are rounded up to the next multiple of the page size. If the calling process does not specify a value or specifies a 0

(zero) value, the value specified in the native object file of the new process is used. If no value is specified in the native object file, the default value of 0

(zero) is used, and enough swap space is guaranteed to launch the process.

If the new process requires a guarantee of available swap space and the system cannot guarantee the required amount, the function call fails, and errno is set to the value of [EAGAIN].

If a value is specified for this field for G-series TNS or accelerated object files, the specified value is used for the main stack of the new process.

The MOM and ANCESTOR fields in the new process differ from those of a process created in the Guardian environment if the new process is named (the pe_name_options field is set to

_TPC_NAME_SUPPLIED or _TPC_GENERATE_NAME). If the calling process is unnamed, then the ANCESTOR field for the new process is set to the caller’s MOM field, and the

MOM field of the new process is null. If the calling process is named, the ANCESTOR field of the new process is set to the ANCESTOR field of the calling process, and the MOM field of the

Hewlett-Packard Company 527186-003

System Functions (t) tdm_execve(2)

new process is null.

The MOM and ANCESTOR fields for the new process are the same as for a process created in the Guardian environment if the new process is unnamed (the pe_name_options field is set to

_TPC_NO_NAME). If the caller is unnamed, the MOM field for the new process is set to the

MOM field of the caller. If the caller is named, the MOM field for the new process is set to the

ANCESTOR field of the calling process.

For detailed information about Guardian process attributes, see the PROCESS_LAUNCH_ procedure in the Guardian Procedure Calls Reference Manual.

Output Structure Information

If the pr_results parameter does not contain a null pointer, it points to an output structure defined in the tdmext.h header file. This structure can contain fields that vary from RVU to RVU, including reserved and filler fields.

First, the output structure must be initialized by using the #define

DEFAULT_PROCESS_EXTENSION_RESULTS. This initialization sets the value of the

pr_len field to the correct value for the current RVU. The value of the pr_len field should not be modified after being set by #define DEFAULT_PROCESS_EXTENSION_RESULTS.

The process_extension_results output structure is described in the

process_extension_results(5) reference page.

RETURN VALUES

If the tdm_execve( ) function returns to the calling process image, an error has occurred; the return value is -1, and errno is set to indicate the error. If the pr_results parameter does not contain a null pointer, the structure it points to returns additional error information, including the

PROCESS_LAUNCH_ error and error detail.

ERRORS

If any of the following conditions occurs, the tdm_execve( ) function sets errno to the corresponding value, file descriptors marked close-on-exec are not closed, signals set to be caught are not set to the default action, and none of these are changed:

The argv[ ] array of pointers

The envp[ ] array of pointers

The elements pointed to by these arrays

The value of the global variable environ

The pointers contained within the global variable environ

The elements pointed to by environ pointers

The effective user ID of the current process

The effective group ID of the current process

[E2BIG]

[EACCES]

The number of bytes used by the new process image’s argument list and environment list is greater than the system-imposed limit. The limit can be obtained by calling the sysconf(_SC_ARG_MAX) function.

One of these conditions exists:

Search permission is denied for the directory components of the pathname prefix to the process image file.

527186-003 Hewlett-Packard Company 8

13

tdm_execve(2) OSS System Calls Reference Manual

The new process image file, any library file, or script file denies execution permission.

The new process image file is not a regular file.

[EAGAIN]

[EFAULT] An address for a parameter in the process_extension structure pointed to by

pe_parms is out of allowable bounds. The Guardian PROCESS_LAUNCH_ error and error detail information is returned in the structure pointed to by the

pr_results parameter, unless pr_results contains a null pointer.

[EHLDSEM] The process tried to create a new process in a different processor while having at least one semadj value.

[EINVAL]

System resources such as disk space, process control block (PCB) space, MAP-

POOL space, stack space, or PFS space are temporarily inadequate.

One of these conditions exists:

An invalid parameter value was supplied in the process_extension structure pointed to by pe_parms. The Guardian PROCESS_LAUNCH_ error and error detail information is returned in the structure pointed to by the pr_results parameter, unless pr_results contains a null pointer.

The new process image file is a binary executable file with invalid attributes.

[EIO]

[ELOOP]

[EMFILE]

Some physical input or output error has occurred. Either a file cannot be opened because of an input or output error, or data has been lost during an input or output transfer. This value is used only for errors on the object file of a loaded program or library, or during data transfer with a Guardian environment home terminal.

Too many symbolic links were encountered in pathname resolution.

The maximum number of files are open. The process attempted to open more than the maximum number of file descriptors allowed for the process. The process file segment (PFS) of the new process might be smaller than that of the calling process.

[ENAMETOOLONG]

One of these is too long:

The pathname pointed to by the path parameter

A component of the pathname pointed to by the path parameter

The intermediate result of pathname resolution when a symbolic link is part of the pathname pointed to by the path parameter

The pathconf( ) function can be called to obtain the applicable limits.

[ENOCPU] The selected processor does not exist, or the selected processor is down or otherwise unavailable for process creation.

[ENODEV] The system cannot find the file system containing the process image file.

8

14 Hewlett-Packard Company 527186-003

System Functions (t) tdm_execve(2)

[ENOENT] One of these conditions exists:

One or more components of the new process image file’s pathname do not exist.

The path parameter points to an empty string.

[ENOEXEC] The new process image file has the appropriate access permissions and is in the

OSS name space, but it is neither in the correct binary executable format nor a valid executable text file.

[ENOMEM] Required resources are not available. Subsequent calls to the same function will not succeed for the same reason.

Possible causes of this error include insufficient primary memory (stack, globals, or heap) for the new process.

[ENOTDIR] A component of the path prefix of the new process image file is not a directory.

[ENOTOSS] The calling process is not an OSS process. The tdm_execve( ) function cannot be called from the Guardian environment.

[ETXTBSY] The new process image file is a pure procedure (shared text) file that is currently open for writing by some process.

[EUNKNOWN]

Unknown error. An unrecognized or very obscure error occurred. If this error occurs, follow site-defined procedures for reporting software problems to

HP.

RELATED INFORMATION

Commands: eld(1), ld(1), nld(1).

Functions: alarm(3), chmod(2), exec(2), _exit(2), exit(3), fcntl(2), fork(2), getenv(3),

putenv(3), semget(2), shmat(2), sigaction(2), system(3), tdm_execvep(2), tdm_fork(2),

tdm_spawn(2), tdm_spawnp(2), times(3), ulimit(2), umask(2).

Files: signal(4).

Miscellaneous: environ(5), process_extension_results(5).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification.

527186-003 Hewlett-Packard Company 8

15

tdm_execvep(2) OSS System Calls Reference Manual

NAME

tdm_execvep - Executes a file with HP extensions

LIBRARY

G-series native OSS processes: /G/system/sysnn/zossksrl

H-series OSS processes: /G/system/zdllnnn/zosskdll

SYNOPSIS

#include <tdmext.h>

[ extern char **environ; ]

int tdm_execvep( const char

∗∗

file,

char

∗∗

const argv[ ],

char

∗∗

const envp[ ],

const struct process_extension

∗∗

pe_parms,

struct process_extension_results

∗∗

pr_results);

PARAMETERS

**environ

file

argv[ ]

envp[ ]

pe_parms pr_results

Points to an array of character pointers to environment strings. The environment strings define the OSS environment for the calling process. The environ array is terminated by a null pointer.

Points to a pathname that identifies the new process image file. If the pathname starts with a slash (/) character, it is the absolute pathname. If this pathname does not start with a slash but does contain a slash, the pathname resolves relative to the current working directory. Otherwise, the pathname contains no slash, and the system searches the directories listed in the PATH environment variable for the file and prefixes the directory in which the file is found.

Specifies an array of character pointers to null-terminated strings containing arguments to be passed to the main function of the new program. argv[0] should point to the null-terminated string containing the filename of the new process image. The last member of this array must be a null pointer.

Specifies an array of character pointers to null-terminated strings that describe the environment for the new process.

Points to the input structure containing Guardian process attributes to be assigned to the new process. The structure must be defined locally to match the definition in the tdmext.h header file. The local structure must be initialized before its first use. Initialization can be done using the #define

DEFAULT_PROCESS_EXTENSION, as defined in the tdmext.h header file.

The initialized values can then be modified as appropriate for the call. When this parameter contains a null pointer, the tdm_execvep( ) function assumes default Guardian attributes.

Points to the output structure containing optional process identification and error information. In case of error, this structure provides additional information, including the PROCESS_LAUNCH_ procedure error and error detail. The structure must be defined locally to match the definition in the tdmext.h header file.

The local structure must be initialized before its first use. Initialization can be done using the #define DEFAULT_PROCESS_EXTENSION_RESULTS, as defined in the tdmext.h header file.

See the process_extension_results(5) reference page for information about the | content of the structure. The tdmext.h header file is not kept current when new |

|

8

16 Hewlett-Packard Company 527186-003

System Functions (t) tdm_execvep(2)

error codes are defined for process creation functions. The list of _TPC_ macros | described in that reference page is not complete; for a current description of error | macros and error codes, see the Guardian header file

$SYSTEM.ZSPIDEF.ZGRDC or the summary of process-creation errors in the |

|

Guardian Procedure Calls Reference Manual (see the table entitled "Summary | of Process Creation Errors").

DESCRIPTION

The tdm_execvep( ) function replaces the current process image with a new process image. The new image is constructed from a regular executable file, called a new process image file. The new process image file is formatted as an executable text or binary file in one of the formats recognized by the tdm_execvep( ) function.

The tdm_execvep( ) function is similar to the tdm_execve( ) function. The main difference is in the way the pathname for the process image file is resolved. tdm_execve( ) always resolves relative pathnames by prefixing the current working directory. tdm_execvep( ) sometimes uses the

PATH environment variable; see Identifying the Process Image File, later in this reference page.

A successful tdm_execvep( ) function call does not return, because the calling process image is overlaid by the new process image.

When a program is executed as a result of a tdm_execvep( ) call, it is entered as a function call:

int main(

int argc,

char

∗∗

argv[ ],

char

∗∗

envp);

Here, the argc parameter is the argument count, the argv[ ] parameter is an array of character pointers to the arguments themselves, and the envp parameter is a pointer to a character array listing the environment variables. The argv[ ] array is terminated by a null pointer. The null pointer is not counted in argc.

The arguments specified by a program using the tdm_execvep( ) function are passed on to the new process image in the corresponding arguments to the main( ) function.

Use From the Guardian Environment

If called from a Guardian process, the actions of this function are undefined, and errno is set to

[ENOTOSS].

Identifying the Process Image File

The tdm_execvep( ) function uses the file parameter to identify the process image file. If the pathname specified as the file parameter starts with a slash (/) character, it is the absolute pathname. If the pathname does not start with a slash but contains a slash, the pathname is resolved relative to the current working directory. Otherwise, the pathname does not contain a slash, and the system searches the directories listed in the PATH environment variable for the file and prefixes the directory in which the file is found.

Passing the Arguments

The argv[ ] parameter is an array of character pointers to null-terminated strings. The last member of this array is a null pointer. These strings constitute the argument list available to the new process image. The value in argv[0] should point to a filename that is associated with the process being started by the tdm_execvep( ) function.

527186-003 Hewlett-Packard Company 8

17

tdm_execvep(2) OSS System Calls Reference Manual

Specifying the Environment

The envp[ ] parameter is an array of character pointers to null-terminated strings. These strings constitute the environment for the new process image. The environment array is terminated with a null pointer.

The number of bytes available for the new process’s combined argument and environment lists has a system-imposed limit. This limit, which includes the pointers and the null terminators on the strings, is available by calling the sysconf(_SC_ARG_MAX) function.

Executing a Binary File

If the file specified as the new process image file is a binary executable file, the tdm_execvep( ) function loads the file directly.

Executing a Text File

If the file specified as the new process image file is not a binary executable file, the

tdm_execvep( ) function examines the file to determine whether it is an executable text file. It checks for a header line in this format:

#! interpreter_name [optional_string]

The #! notation identifies the file as an executable text file. The new process image filename is constructed from the process image filename in the interpreter_name string, treating it like the

file parameter. The Guardian input and output structures pointed to by the pe_parms and

pr_results parameters apply to the command interpreter as they would to any process file.

The arguments passed to the new process are modified as listed:

argv[0] is set to the name of the command interpreter.

If the optional_string portion is present, argv[1] is set to optional_string.

The next element of argv[ ] is set to the original value of file.

The remaining elements of argv[ ] are set to the original elements of argv[ ], starting with

argv[1]. The original argv[0] is discarded.

The S_ISUID and S_ISGID mode bits of an executable text file are honored. Those bits are ignored for the interpreter_name command interpreter.

When the File Is Invalid

If the process image file is not a valid executable object, or if the text file does not contain the header line, the tdm_execvep( ) function invokes the interpreter_name command interpreter as the new process image and passes these arguments to it:

argv[0] is set to the string sh.

argv[1] is set to the original value of the file parameter.

The remaining elements of argv[ ] are set to the original elements of argv[ ], starting with

argv[1].

The original argv[0] is discarded.

8

18 Hewlett-Packard Company 527186-003

System Functions (t) tdm_execvep(2)

Open Files

File descriptors open in the calling process image remain open in the new process image, except for those:

Whose close-on-exec flag FD_CLOEXEC is set (see the fcntl(2) reference page)

Opened using a Guardian function or procedure call

For a G-series TNS process image or an accelerated processs image only, if the process file segment (PFS) of the new process image is smaller than the process file segment of the calling process image and if the calling process image has a large number of file descriptors open, the system might not be able to propagate all the open file descriptors to the new process image. When this situation occurs, the function call fails, and errno is set to the value of [EMFILE].

For those file descriptors that remain open, all attributes of the open file descriptor, including file locks, remain unchanged. All directory streams are closed.

Open Pipes and FIFOs

A pipe or FIFO associated with an open file descriptor in the calling process remains connected in the new process. If the new process runs in a different processor than the calling process, the processor that runs the new process must also be running an OSS pipe server process.

If no OSS pipe server process is running in the new processor, the new process cannot use the pipe or FIFO; calls specifying the file descriptor for the pipe or FIFO fail with errno set to

[EWRONGID]. The new process can only close the invalid file descriptor.

Existing Sockets

A socket associated with an open file descriptor in the calling process remains connected in the new process when the new process runs in the same processor as the calling process.

When the new process runs in a different processor than the calling process, the processor that runs the new process must also be running a socket transport agent process. If no socket transport agent process is running in the new processor, the new process cannot use the socket; calls specifying the file descriptor for the socket fail with errno set to [EWRONGID]. The new process can only close the invalid file descriptor.

Shared Memory

Any attached shared memory segments are detached from the new process by a successful call to the tdm_execvep( ) function. See the shmat(2) reference page for additional information about shared memory segment use.

Semaphores

Semaphore set IDs attached to the calling process are also attached to the new process if the new process executes in the same processor as the calling process. The new process also inherits the adjust-on-exit (semadj) values of the calling process if both processes are in the same processor.

A semaphore set cannot be shared when a semadj value exists for the calling process and the new process is created in a different processor. When that condition exists, a call to the

tdm_execvep( ) function fails and errno is set to [EHLDSEM].

See the semget(2) reference page for additional information about semaphore use.

Signals

Signals set to:

The default action (SIG_DFL) in the calling process image are set to the default action in the new process image.

527186-003 Hewlett-Packard Company 8

19

tdm_execvep(2) OSS System Calls Reference Manual

Be ignored (SIG_IGN) by the calling process image are set to be ignored by the new process image.

Cause abnormal termination (SIG_ABORT) in the calling process image are set to that | action in the new process image.

Cause entry into the debugger (SIG_DEBUG) in the calling process image are set to that | action in the new process image.

Be caught by the calling process image are set to the default action in the new process image.

See the signal(4) reference page either online or in the Open System Services System Calls Refer- |

ence Manual.

User ID and Group ID

If the set-user-ID mode bit (S_ISUID) of the new process image file is set (see the chmod(2) reference page), the effective user ID of the new process image is set to the user ID of the owner of the new process image file. Similarly, if the set-group-ID mode bit (S_ISGID) of the new process image file is set, the effective group ID of the new process image is set to the group ID of the new process image file. The real user ID, real group ID, and supplementary group IDs of the new process image remain the same as those of the calling process image. The effective user ID and effective group ID of the new process image are saved (as the saved-set user ID and the saved-set group ID) for use by the setuid( ) function.

OSS Attributes

These OSS attributes of the calling process image are unchanged after successful completion of the tdm_execvep( ) function:

OSS process ID (PID)

Parent OSS process ID

Process group ID

Session membership

Real user ID

Real group ID

Supplementary group IDs

The time left until an alarm clock signal is posted (see the alarm(3) reference page)

Current working directory

Root directory

File mode creation mask (see the umask(2) reference page)

Process signal mask (see the sigprocmask(2) reference page)

Pending signals (see the sigpending(2) reference page)

The tms_utime, tms_stime, tms_cutime, and tms_cstime fields of the tms structure

8

20 Hewlett-Packard Company 527186-003

System Functions (t) tdm_execvep(2)

File size limit (see the ulimit(2) reference page)

Upon successful completion, the tdm_execvep( ) function marks the st_atime field of the file for update.

The POSIX.1 standard does not specify the effect on the st_atime field when the tdm_execvep( ) function call fails but does find the file. Neither does the HP implementation guarantee the outcome. Under these circumstances, this field should not be used for further processing.

Default Guardian Attributes

If the pe_parms parameter contains a null pointer, the newly created OSS process retains all these default Guardian attributes of the process that calls the tdm_execvep( ) function:

Priority

Processor on which the process executes

Home terminal

Job ID

DEFINE mode switch

Process access ID (PAID), unless the S_ISUID mode bit of the new process image file is set

Security group list

Job ancestor or GMOM

Unread system message index (PCBMCNT)

This attribute assignment is different from the assignment made when creating a new process with Guardian procedures.

Outstanding incoming and outgoing message limits

This attribute assignment is different from the assignment made when creating a new process with Guardian procedures.

Login, remote login, and saveabend flags

File creation mask

If the pe_parms parameter contains a null pointer, the default Guardian attributes of the new process that differ from those of the calling process are:

No segments created or shared using Guardian system procedures such as

SEGMENT_ALLOCATE_ are inherited.

The program file is the file specified in the tdm_execvep( ) call.

The library file is specified in the program file.

The child process does not inherit the parent process extended swap file (if any). For a

G-series TNS process or an accelerated process, the extended data segment is managed by the Kernel Managed Storage Facility (KMSF) unless an extended swap file is specified in the pe_extswap_file_name field of the process_extension structure described elsewhere in this reference page.

527186-003 Hewlett-Packard Company 8

21

tdm_execvep(2) OSS System Calls Reference Manual

The process name for the new process is system-generated if the RUNNAMED option is set in the program file. Otherwise the process is unnamed.

The size of the data segment of the new process is set in the program file.

The remote login flag (PCBREMID) is set to zero (off) if the program file has its

S_ISUID mode bit set. Otherwise, the remote login flag is set the same as for the caller.

The size of the extended data segment of the new process is set in the program file.

The DEFINEs inherited by the new process depend on the setting of DEFINE mode in the caller. If DEFINE mode in the caller is ON, all the caller’s DEFINEs are inherited.

If DEFINE mode is OFF, no DEFINEs are inherited.

The process identification number (PIN) of the new process is unrelated to that of the calling process. Usually, the PIN of the new process is unrestricted. However, the PIN can be restricted to the range 0 through 254 under the following conditions:

— The HIGHPIN flag is not set in, or is absent from, the program file or any library file.

_TPC_HIGHPIN_OFF is specified in the pe_create_options field of the

process_extension structure.

— The restriction is inherited. See the description of

_TPC_IGNORE_FORCEPIN_ATTR in the pe_create_options field of the

process_extension structure for more information about controlling inheritance.

The creator access ID (CAID) is set to the process access ID (PAID) of the calling process.

The PAID depends on whether the S_ISUID mode bit of the process image file is set. If that bit is set, the PAID is based on the file owner ID. If not, the PAID is the same as for the caller. (The S_ISUID mode bit of the image file has no effect on the security group list.)

The MOM field for the new process depends on whether the calling process is named. If it is named, the MOM field of the new process is set to the caller’s ANCESTOR field.

Otherwise, the MOM field of the new process is set to the caller’s MOM field.

System debugger selection for the new process is based on INSPECT mode.

Code breakpoints and memory breakpoints are not inherited.

For detailed information about Guardian process attributes, see the PROCESS_LAUNCH_ procedure in the Guardian Procedure Calls Reference Manual.

Setting Guardian Attributes

The input structure pointed to by the pe_parms parameter permits the setting of Guardian attributes for the new process.

First, the input structure must be initialized to the default values (see Default Guardian Attri-

butes, earlier in this reference page) using the #define DEFAULT_PROCESS_EXTENSION.

After the data structure is initialized, the values can be set using literals that are defined in the

tdmext.h header file.

If any optional parameter specified in the structure pointed to by pe_parms is not passed, the new process assumes the corresponding default value.

8

22 Hewlett-Packard Company 527186-003

System Functions (t) tdm_execvep(2)

The input structure is defined in the tdmext.h header file. This structure can contain fields that vary from release version update (RVU) to RVU, including reserved and filler fields.

In the current release version update (RVU), these fields are meaningful:

typedef struct process_extension { long pe_len; char *pe_library_name; char *pe_swap_file_name; char *pe_extswap_file_name; short pe_priority; short pe_cpu; short pe_name_options; char filler_1[2]; char *pe_process_name; char *pe_hometerm; short pe_memory_pages; short pe_jobid; short pe_create_options; char filler_2[2]; char *pe_defines; short pe_defines_len; short pe_debug_options; long pe_pfs_size; short pe_OSS_options; char filler_3[2]; long pe_mainstack_max; long pe_heap_max; long pe_space_guarantee;

} process_extension_def;

The input structure passes this information:

pe_len

Specifies the size of the structure in bytes. This value is set by the #define

DEFAULT_PROCESS_EXTENSION and should not be changed.

pe_library_name

Points to the name of the user library to be bound to the new process. The string that is pointed to is null-terminated and in OSS name format. If the pointer points to a zero-length string (a NULL character), the new process runs with no user library. An equivalent call to the Guardian PROCESS_LAUNCH_ procedure does this by setting the library filename length to -1.

This field is used only for G-series TNS or accelerated new process image files.

If a value is specified for this field for native object files, the specified value is ignored.

pe_swap_file_name

Points to a null-terminated string specifying the name of a file in the Guardian file system to be used as the swap file for the stack segment. For example, if the

Guardian file name is $A.B.C, the name used is /G/a/b/c.

This file cannot have the same name as that of a file used in a preceding call to the tdm_fork( ) function.

This field is not used in the current RVU of Open System Services. It exists for compatibility with older RVUs. Any specified value is checked for validity but otherwise ignored.

527186-003 Hewlett-Packard Company 8

23

tdm_execvep(2)

8

24

OSS System Calls Reference Manual pe_extswap_file_name

Points to a null-terminated string specifying the name of a disk file in the Guardian file system to be used as the swap file for the extended data segment. For example, if the Guardian file name is $A.B.D, the name used is /G/a/b/d.

This file cannot have the same name as that of a file used in a preceding call to the tdm_fork( ) function.

This field is used only for G-series TNS or accelerated new process image files.

If a value is specified for this field for native object files, the specified value is checked for validity but otherwise ignored.

By default, the new process uses KMSF to manage its extended swap segment.

HP recommends using the default.

pe_priority

Specifies the priority of the new process.

pe_cpu

Specifies the processor on which the new process will execute. The OSS process

ID (PID) of the process remains unchanged. This field is used to distribute system load.

pe_name_options

Specifies process naming as:

_TPC_GENERATE_NAME

The system generates the name.

_TPC_NAME_SUPPLIED

The process name is indicated by the pe_process_name field.

_TPC_NO_NAME

The new process is unnamed.

pe_process_name

Points to the null-terminated Guardian process name if

_TPC_NAME_SUPPLIED is specified in the pe_name_options field. For example, if the Guardian process name is $DELM, the name used is /G/delm.

pe_hometerm Points to the null-terminated name in the Guardian file system for the home terminal. For example, if the Guardian name is $ztnt.#xyz, the name used is

/G/ztnt/#xyz.

pe_memory_pages

Specifies the size of the data stack in 2 KB units. This field is used only for Gseries TNS or accelerated new process image files. If a value is specified for this field for native object files, the specified value is checked for validity but otherwise ignored.

pe_jobid

Specifies the job ID of the new process.

pe_create_options

Specifies process creation options as:

_TPC_BOTH_DEFINES

Propagates the current DEFINEs and the DEFINEs indicated in the input structure.

_TPC_ENABLE_DEFINES

Enables DEFINEs when set if

Hewlett-Packard Company 527186-003

System Functions (t) tdm_execvep(2) pe_defines

_TPC_OVERRIDE_DEFMODE is also set. Disables

DEFINEs when not set.

_TPC_HIGHPIN_OFF

Restricts the new process to a PIN in the range 0 through 254.

This restriction is rarely useful for an OSS process; it allows obsolescent Guardian interfaces to interact with the process.

By default, this restriction is inherited by any child or successor process. The default can be overridden by using the

_TPC_IGNORE_FORCEPIN_ATTR field.

_TPC_IGNORE_FORCEPIN_ATTR

Ignores the _TPC_HIGHPIN_OFF restriction specified for or inherited by the caller or parent process. When

_TPC_IGNORE_FORCEPIN_ATTR is specified, the resulting process has a restricted PIN only if _TPC_HIGHPIN_OFF is also specified or if the object file for the program or a user library lacks the HIGHPIN attribute.

_TPC_OVERRIDE_DEFMODE

Specifies that the DEFINE mode of the new process is to be set according to the _TPC_ENABLE_DEFINES option rather than to the caller’s current DEFINE mode.

_TPC_PROCESS_DEFINES_ONLY

Propagates only the current set of DEFINEs.

_TPC_SUPPLIED_DEFINES_ONLY

Propagates only the DEFINEs indicated by the pe_defines field.

Points to a specified saved set of DEFINEs created by using the Guardian

DEFINESAVE procedure. These DEFINEs are propagated to the new process if either _TPC_SUPPLIED_DEFINES_ONLY or _TPC_BOTH_DEFINES is specified in the pe_create_options field.

Note: This string is not null-terminated.

pe_defines_len

Specifies the length of the string in the pe_defines field.

pe_debug_options

Provides control over the selection between the default and symbolic debuggers and over the creation of the saveabend file. A saveabend file can be examined by using a symbolic debugger to determine the cause of the abnormal termination.

In addition, you can use this option to force the new process to enter the default debugger before executing. Possible options are:

_TPC_CODEFILE_INSPECT_SAVEABEND

Uses the saveabend and INSPECT mode flags in the program file.

_TPC_DEBUG_NOSAVE

Uses the default debugger but does not create a saveabend file.

527186-003 Hewlett-Packard Company 8

25

tdm_execvep(2) OSS System Calls Reference Manual

8

26

_TPC_DEBUG_SAVEABEND

Uses the default debugger and creates a saveabend file.

_TPC_ENTER_DEBUG

Starts the new process in the default debugger.

_TPC_INSPECT_NOSAVE

Uses the symbolic debugger but does not create a saveabend file.

_TPC_INSPECT_SAVEABEND

Uses the symbolic debugger and creates a saveabend file.

pe_pfs_size

Specifies the size of the process file segment (PFS) for the new process (this field is ignored).

pe_OSS_options

Specifies OSS options. No special action on signals is the default and only current OSS option.

pe_mainstack_max

Specifies the maximum size of the main stack in bytes for the new process.

If the calling process specifies a value, the value must be less than 32 MB. If the calling process does not specify a value or specifies a 0 (zero) value, the value specified in the object file of the new process is used. If no value is specified in the object file, the default value of 1 MB (for TNS/R systems) or 2 MB (for

TNS/E systems) is used.

pe_heap_max Specifies the maximum size of the heap in bytes for the new process if it is a native process.

See the C/C++ Programmer’s Guide description of the HEAP pragma for guidance on the use of nonzero values for this field.

If a value is specified for this field for G-series TNS or accelerated object files, the specified value is ignored.

pe_space_guarantee

Specifies the minimum available swap space to guarantee for the new process.

If the calling process specifies a value, the value must be less than or equal to a multiple of the page size of the processor in which the new process will run.

Values less than a multiple of the page size are rounded up to the next multiple of the page size. If the calling process does not specify a value or specifies a 0

(zero) value, the value specified in the native object file of the new process is used. If no value is specified in the native object file, the default value of 0

(zero) is used, and enough swap space is guaranteed to launch the process.

If the new process requires a guarantee of available swap space and the system cannot guarantee the required amount, the function call fails, and errno is set to the value of [EAGAIN].

If a value is specified for this field for G-series TNS or accelerated object files, the specified value is used for the main stack of the new process.

The MOM and ANCESTOR fields in the new process differ from those of a process created in the Guardian environment if the new process is named (the pe_name_options field is set to

_TPC_NAME_SUPPLIED or _TPC_GENERATE_NAME). If the calling process is unnamed, the ANCESTOR field for the new process is set to the caller’s MOM field, and the

MOM field of the new process is null. If the calling process is named, the ANCESTOR field of

Hewlett-Packard Company 527186-003

System Functions (t) tdm_execvep(2)

the new process is set to the ANCESTOR field of the calling process, and the MOM field of the new process is null.

The MOM and ANCESTOR fields for the new process are the same as for a process created in the Guardian environment if the new process is unnamed (the pe_name_options field is set to

_TPC_NO_NAME). If the caller is unnamed, the MOM field for the new process is set to the

MOM field of the caller. If the caller is named, the MOM field for the new process is set to the

ANCESTOR field of the calling process.

For detailed information about Guardian process attributes, see the PROCESS_LAUNCH_ procedure in the Guardian Procedure Calls Reference Manual.

Output Structure Information

If the pr_results parameter does not contain a null pointer, it points to an output structure defined in the tdmext.h header file. This structure can contain fields that vary from RVU to RVU, including reserved and filler fields.

First, the output structure must be initialized by using the #define

DEFAULT_PROCESS_EXTENSION_RESULTS. This initialization sets the value of the

pr_len field to the correct value for the current RVU. The value of the pr_len field should not be modified after being set by #define DEFAULT_PROCESS_EXTENSION_RESULTS.

The process_extension_results output structure is described in the

process_extension_results(5) reference page.

RETURN VALUES

If the tdm_execvep( ) function returns to the calling process image, an error has occurred; the return value is -1, and errno is set to indicate the error. If the pr_results parameter does not contain a null pointer, the structure it points to returns additional error information, including the

PROCESS_LAUNCH_ error and error detail.

ERRORS

If any of the following conditions occurs, the tdm_execvep( ) function sets errno to the corresponding value, file descriptors marked close-on-exec are not closed, signals set to be caught are not set to the default action, and none of these are changed:

The argv[ ] array of pointers

The envp[ ] array of pointers

The elements pointed to by these arrays

The value of the global variable environ

The pointers contained within the global variable environ

The elements pointed to by environ pointers

The effective user ID of the current process

The effective group ID of the current process

[E2BIG]

[EACCES]

The number of bytes used by the new process image’s argument list and environment list is greater than the system-imposed limit. The limit can be obtained by calling the sysconf(_SC_ARG_MAX) function.

One of these conditions exists:

Search permission is denied for the directory components of the pathname prefix to the process image file.

527186-003 Hewlett-Packard Company 8

27

tdm_execvep(2) OSS System Calls Reference Manual

The new process image file, any library file, or script file denies execution permission.

The new process image file is not a regular file.

[EAGAIN]

[EFAULT] An address for a parameter in the process_extension structure pointed to by

pe_parms is out of allowable bounds. The Guardian PROCESS_LAUNCH_ error and error detail information is returned in the structure pointed to by the

pr_results parameter, unless pr_results contains a null pointer.

[EHLDSEM] The process tried to create a new process in a different processor while having at least one semadj value.

[EINVAL]

System resources such as disk space, process control block (PCB) space, MAP-

POOL space, stack space, or PFS space are temporarily inadequate.

One of these conditions exists:

An invalid parameter value was supplied in the process_extension structure pointed to by pe_parms. The Guardian PROCESS_LAUNCH_ error and error detail information is returned in the structure pointed to by the pr_results parameter, unless pr_results contains a null pointer.

The new process image file is a binary executable file with invalid attributes.

[EIO]

[ELOOP]

[EMFILE]

Some physical input or output error has occurred. Either a file cannot be opened because of an input or output error or data has been lost during an input or output transfer. This value is used only for errors on the object file of a loaded program or library, or during data transfer with a Guardian environment home terminal.

Too many symbolic links were encountered in pathname resolution.

The maximum number of files are open. The process attempted to open more than the maximum number of file descriptors allowed for the process. The process file segment (PFS) of the new process might be smaller than that of the calling process.

[ENAMETOOLONG]

One of these is too long:

The pathname pointed to by the file parameter

A component of the pathname pointed to by the file parameter

The intermediate result of pathname resolution when a symbolic link is part of the value specified by the file parameter

The pathconf( ) function can be called to obtain the applicable limits.

[ENOCPU] The selected processor does not exist, or the selected processor is down or otherwise unavailable for process creation.

[ENODEV] The system cannot find the file system containing the process image file.

8

28 Hewlett-Packard Company 527186-003

System Functions (t) tdm_execvep(2)

[ENOENT] One of these conditions exists:

One or more components of the new process image file’s pathname do not exist.

The file parameter points to an empty string.

[ENOEXEC] The command interpreter could not be invoked following failure to execute the process image file identified by the file parameter.

[ENOMEM] Required resources are not available. Subsequent calls to the same function will not succeed for the same reason.

Possible causes of this error include insufficient primary memory (stack, globals, or heap) for the new process.

[ENOTDIR] A component of the path prefix of the new process image file is not a directory.

[ENOTOSS] The calling process is not an OSS process. The tdm_execvep( ) function cannot be used from the Guardian environment.

[ETXTBSY] The new process image file is a pure procedure (shared text) file that is currently open for writing by some process.

[EUNKNOWN]

Unknown error. An unrecognized or very obscure error occurred. If this error occurs, follow site-defined procedures for reporting software problems to

HP.

RELATED INFORMATION

Commands: eld(1), ld(1), nld(1).

Functions: alarm(3), chmod(2), exec(2), _exit(2), exit(3), fcntl(2), fork(2), getenv(3),

putenv(3), semget(2), shmat(2), sigaction(2), system(3), tdm_execve(2), tdm_fork(2),

tdm_spawn(2), tdm_spawnp(2), times(3), ulimit(2), umask(2).

Files: signal(4).

Miscellaneous: environ(5), process_extension_results(5).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification.

527186-003 Hewlett-Packard Company 8

29

tdm_fork(2) OSS System Calls Reference Manual

NAME

tdm_fork - Creates a new process with HP extensions

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <tdmext.h> pid_t tdm_fork(

const struct process_extension *pe_parms,

struct process_extension_results *pr_results);

PARAMETERS

pe_parms pr_results

Points to the input structure containing Guardian process attributes to be assigned to the child process. The structure is defined in the tdmext.h header file.

When this parameter contains a null pointer, the tdm_fork( ) function assumes default Guardian attributes. Otherwise, the structure must be defined locally and initialized before its first use. Initialization is done using the #define

DEFAULT_PROCESS_EXTENSION, as defined in the tdmext.h header file.

The initialized values can then be modified as appropriate for the call.

Points to the output structure containing optional process identification and error information. On successful return, this information includes the Guardian process handle and OSS process ID (PID) of the process. If the call is not successful, the OSS error number and Guardian PROCESS_LAUNCH_ procedure error and error detail are returned in this structure. The structure is defined in the

tdmext.h header file.

The structure must be defined locally and initialized before its first use. Initialization is done using the #define

DEFAULT_PROCESS_EXTENSION_RESULTS, as defined in the tdmext.h header file.

See the process_extension_results(5) reference page for information about the | content of the structure. The tdmext.h header file is not kept current when new | error codes are defined for process creation functions. The list of _TPC_ macros | described in that reference page is not complete; for a current description of error | macros and error codes, see the Guardian header file

$SYSTEM.ZSPIDEF.ZGRDC or the summary of process-creation errors in the |

|

Guardian Procedure Calls Reference Manual (see the table entitled "Summary | of Process Creation Errors").

DESCRIPTION

The tdm_fork( ) function creates a child OSS process. The created process is referred to as the child and the caller as the parent. The child process executes the same program file as the parent.

The child process retains many of its parent’s OSS process attributes and obtains system-derived values for others. For Guardian process attributes, the child process can retain default values or can have values specified in the tdm_fork( ) call.

8

30 Hewlett-Packard Company 527186-003

System Functions (t) tdm_fork(2)

Use From the Guardian Environment

If called from a Guardian process, the actions of this function are undefined and errno is set to

[ENOTOSS].

OSS Attributes

The child process inherits the following OSS attributes from the parent process:

Environment

Close-on-exec flags

Signal-handling settings

Saved-set-user-ID mode bit

Saved-set-group-ID mode bit

Process group ID

Current directory

Root directory

File mode creation mask

File size limit (see the ulimit(2) reference page)

Attached semaphore set IDs

Attached shared memory segments

The OSS attributes of the child process differ from those of the parent process in the following ways:

The child process has a unique OSS process ID (PID) and does not match any active process group ID.

The parent process ID of the child process matches the OSS process ID of the parent.

The child process has its own copy of the parent process’s file descriptors. However, each of the child’s file descriptors shares a common file pointer with the corresponding file descriptor of the parent process.

The child process does not inherit any file open created by a Guardian function or procedure call.

The child process does not inherit file locks.

The child process’s tms_utime, tms_stime, tms_cutime, and tms_cstime values are set to 0 (zero).

Any pending alarms are cleared in the child process.

Any signals pending for the parent process are not inherited by the child process.

Any adjust-on-exit (semadj) values of the parent process are not inherited by the child process.

527186-003 Hewlett-Packard Company 8

31

tdm_fork(2) OSS System Calls Reference Manual

The child process shares directory streams with the parent. They share the same block of directory entries. When reading an entry, the buffer pointer is advanced by one entry.

From the perspective of either process, an entry might be skipped.

If both processes call the readdir( ) function for a shared stream, the results are undefined. After such a call by both functions, another call to the readdir( ) function by either process has undefined results.

Default Guardian Attributes

If the pe_parms parameter contains a null pointer, then the child process inherits all the following default Guardian attributes from the parent process:

Program file

Any library file

The size and contents of any instance data segments for native libraries

Priority (the child process inherits the parent’s current priority)

Processor on which the process executes

Home terminal

For G-series TNS processes and accelerated processes, the size and contents of the data segment

For G-series TNS processes and accelerated processes, the size and contents of the extended data segment

The assignment of the data segment size is different from the assignment made when creating a child process with Guardian procedures.

For native processes, the contents of the stack segment from its origin to the currently in-use location; the rest of the child process stack is 0 (zero)

For native processes, the size and contents of the globals-heap segment

Job ID

DEFINE mode

Creator access ID (CAID)

Process access ID (PAID)

Security group list

Job ancestor or GMOM

Unread system message index (PCBMCNT)

This attribute assignment is different from the assignment made when creating a child process with Guardian procedures.

Outstanding incoming and outgoing message limits

This attribute assignment is different from the assignment made when creating a child process with Guardian procedures.

8

32 Hewlett-Packard Company 527186-003

System Functions (t) tdm_fork(2)

Login, remote login, and saveabend flags

File creation mask

System debugger selection (based on Inspect mode and OSS read access rights on the program file)

If the pe_parms parameter contains a null pointer, then the default Guardian attributes of the child process differ from those of the parent process in the following ways:

Segments created or shared using Guardian procedures such as

SEGMENT_ALLOCATE_ are not inherited.

The child process does not inherit the parent process extended swap file (if any). For a

G-series TNS process or an accelerated process, the extended data segment is managed by the Kernel Managed Storage Facility (KMSF) unless an extended swap file is specified in the pe_extswap_file_name field of the process_extension structure described elsewhere in this reference page.

The child’s process name is system-generated if the RUNNAMED option is set in the program file. Otherwise, the process is unnamed.

The DEFINEs inheritance for the child is based on the parent’s DEFINE mode.

The process identification number (PIN) of the child process is unrelated to that of the parent process. Usually, the PIN of the child process is unrestricted. However, the PIN can be restricted to the range 0 through 254 under the following conditions:

— The HIGHPIN flag is not set in, or is absent from, the program file or any library file.

_TPC_HIGHPIN_OFF is specified in the pe_create_options field of the

process_extension structure, described elsewhere in this reference page.

— The restriction is inherited. See _TPC_IGNORE_FORCEPIN_ATTR in the

pe_create_options field of the process_extension structure, described elsewhere in this reference page, for more information about controlling inheritance.

The MOM field for the child process is set to 0 (zero).

Code breakpoints and memory breakpoints are not inherited.

For detailed information about Guardian process attributes, see the PROCESS_LAUNCH_ procedure in the Guardian Procedure Calls Reference Manual.

Setting Guardian Attributes

The input structure pointed to by the pe_parms parameter permits the setting of Guardian attributes for the child process.

First, the input structure must be initialized to the default values (see Default Guardian Attri-

butes, earlier in this reference page) using the #define DEFAULT_PROCESS_EXTENSION.

After the data structure is initialized, the values can be set using literals that are defined in the

tdmext.h header file.

If any optional parameter specified in the structure pointed to by pe_parms is not passed, the child process assumes the corresponding default value.

The input structure is defined in the tdmext.h header file. This structure can contain fields that vary from release to release, including reserved and filler fields.

527186-003 Hewlett-Packard Company 8

33

tdm_fork(2) OSS System Calls Reference Manual

8

34

The following fields are meaningful:

typedef struct process_extension { long pe_len; char *pe_library_name; char *pe_swap_file_name; char *pe_extswap_file_name; short pe_priority; short pe_cpu; short pe_name_options; char filler_1[2]; char *pe_process_name; char *pe_hometerm; short pe_memory_pages; short pe_jobid; short pe_create_options; char filler_2[2]; char *pe_defines; short pe_defines_len; short pe_debug_options; long pe_pfs_size; short pe_OSS_options; char filler_3[2]; long pe_mainstack_max; long pe_heap_max; long pe_space_guarantee;

} process_extension_def;

The input structure passes the following information:

pe_len

Specifies the size of the structure in bytes. This value is set by #define

DEFAULT_PROCESS_EXTENSION and should not be changed.

pe_library_name

Is not used with the tdm_fork( ) function.

pe_swap_file_name

Points to a null-terminated string specifying the name of a file in the Guardian file system to be used as the swap file for the stack segment. For example, if the

Guardian filename is $A.B.C, then the name used here is /G/a/b/c.

This field is not used in the current release of Open System Services. It exists for compatibility with older releases. Any specified value is checked for validity but otherwise ignored.

pe_extswap_file_name

Points to a null-terminated string specifying the name of a disk file in the Guardian file system to be used as the swap file for the extended data segment. For example, if the Guardian filename is $A.B.D, then the name used here is

/G/a/b/d.

This field is used only for G-series TNS or accelerated child processes. If a value is specified for this field for native object files, the specified value is validated but otherwise ignored.

By default, the new process uses KMSF to manage its extended swap segment.

HP recommends using the default.

Hewlett-Packard Company 527186-003

System Functions (t) tdm_fork(2) pe_priority

Specifies the priority of the child process.

pe_cpu

Specifies the processor on which the child process will execute. The only valid values for the tdm_fork( ) function are -1 (the default value) and the current processor number. Each of these values has the effect of running the child process on the same processor as the parent.

pe_name_options

Specifies process naming as follows:

_TPC_GENERATE_NAME

The system generates the name.

_TPC_NAME_SUPPLIED

The process name is indicated by the pe_process_name field.

_TPC_NO_NAME

The child process is unnamed.

pe_process_name

Points to the null-terminated Guardian process name if

_TPC_NAME_SUPPLIED is specified in the pe_name_options field. For example, if the Guardian process name is $DELM, then the name used here is

/G/delm.

pe_hometerm Points to the null-terminated name in the Guardian file system for the home terminal. For example, if the Guardian name is $ztnt.#xyz, then the name used here is /G/ztnt/#xyz.

pe_memory_pages

Specifies the size of the data stack in 2K-byte units. This field is used only for

G-series TNS or accelerated child processes. If a value is specified for this field for native object files, the specified value is checked for validity but otherwise ignored.

pe_jobid

Specifies the job ID of the child process.

pe_create_options

Specifies process creation options as follows:

_TPC_BOTH_DEFINES

Propagates the current DEFINEs and the DEFINEs indicated in the input structure.

_TPC_ENABLE_DEFINES

Enables DEFINEs when set if

_TPC_OVERRIDE_DEFMODE is also set. Disables

DEFINEs when not set.

_TPC_HIGHPIN_OFF

Restricts the child process to a PIN in the range 0 through 254.

This restriction is rarely useful for an OSS process; it allows obsolescent Guardian interfaces to interact with the process.

By default, this restriction is inherited by any child or successor process. The default can be overridden by using the

_TPC_IGNORE_FORCEPIN_ATTR field.

527186-003 Hewlett-Packard Company 8

35

tdm_fork(2) OSS System Calls Reference Manual pe_defines

_TPC_IGNORE_FORCEPIN_ATTR

Ignores the _TPC_HIGHPIN_OFF restriction specified for or inherited by the parent process. When

_TPC_IGNORE_FORCEPIN_ATTR is specified, the resulting process has a restricted PIN only if _TPC_HIGHPIN_OFF is also specified or if the object file for the program or a user library lacks the HIGHPIN attribute.

_TPC_OVERRIDE_DEFMODE

Specifies that the DEFINE mode of the child process is to be set according to the _TPC_ENABLE_DEFINES option rather than to the parent’s current DEFINE mode.

_TPC_PROCESS_DEFINES_ONLY

Propagates only the current set of DEFINEs.

_TPC_SUPPLIED_DEFINES_ONLY

Propagates only the DEFINEs indicated by the pe_defines field.

Points to a specified saved set of DEFINEs created using the Guardian

DEFINESAVE procedure. These DEFINEs are propagated to the child process if either _TPC_SUPPLIED_DEFINES_ONLY or _TPC_BOTH_DEFINES is specified in the pe_create_options field.

Note: This string is not null-terminated.

pe_defines_len

Specifies the length of the string in the pe_defines field.

pe_debug_options

Provides control over the selection between debuggers and over the creation of the saveabend file. A saveabend file can be examined using the symbolic debugger to determine the cause of the abnormal termination. In addition, you can use this option to force the created child process to enter the default system debugger on return from the tdm_fork( ) function.

Possible options are:

_TPC_CODEFILE_INSPECT_SAVEABEND

Uses the saveabend and Inspect flags in the program file.

_TPC_DEBUG_NOSAVE

Uses the default system debugger but does not create a saveabend file.

_TPC_DEBUG_SAVEABEND

Uses the default system debugger and creates a saveabend file.

_TPC_ENTER_DEBUG

Starts the child process in the default system debugger.

_TPC_INSPECT_NOSAVE

Uses the symbolic debugger but does not create a saveabend file.

8

36 Hewlett-Packard Company 527186-003

System Functions (t) tdm_fork(2)

_TPC_INSPECT_SAVEABEND

Uses the symbolic debugger and creates a saveabend file.

pe_pfs_size

Specifies the size of the process file segment (PFS) for the child process (this field is ignored).

pe_OSS_options

Specifies OSS options. No special action on signals is the default and only current OSS option.

pe_mainstack_max

Specifies the maximum size of the main stack in bytes for the child process.

If the parent process specifies a value, the value must be less than 32 megabytes.

If the parent process does not specify a value or specifies a 0 (zero) value, then the value specified in the object file of the child process is used. If no value is specified in the object file, then the default value of 1 megabyte is used.

pe_heap_max Specifies the maximum size of the heap in bytes for the child process if it is a native process.

See the C/C++ Programmer’s Guide description of the HEAP pragma for guidance on the use of nonzero values for this field.

If a value is specified for this field for G-series TNS or accelerated object files, the specified value is ignored.

pe_space_guarantee

Specifies the minimum available swap space to guarantee for the child process.

If the parent process specifies a value, the value must be less than or equal to a multiple of the page size of the processor in which the child process will run.

Values less than a multiple of the page size are rounded up to the next multiple of the page size. If the parent process specifies a nonzero value, that value is used for the child process; otherwise, the child process inherits the space guaran|

| tee attribute of the parent process.

If the child process requires a guarantee of available swap space and the system cannot guarantee the required amount, the function call fails and errno is set to the value of value [EAGAIN].

If a value is specified for this field for G-series TNS or accelerated object files, the specified value is used for the main stack of the child process.

For detailed information about Guardian process attributes, see the PROCESS_LAUNCH_ procedure in the Guardian Procedure Calls Reference Manual.

Output Structure Information

If the pr_results parameter does not contain a null pointer, it points to an output structure defined in the tdmext.h header file. This structure can contain fields that vary from release to release, including reserved and filler fields.

First, the output structure must be initialized using the #define

DEFAULT_PROCESS_EXTENSION_RESULTS. This initialization sets the value of the

pr_len field to the correct value for the current release. The value of the pr_len field should not be modified after being set by #define DEFAULT_PROCESS_EXTENSION_RESULTS.

The process_extension_results output structure is described in the

process_extension_results(5) reference page.

527186-003 Hewlett-Packard Company 8

37

tdm_fork(2) OSS System Calls Reference Manual

Shared Memory

Any attached shared memory segments are attached to both the child process and the parent process when both processes execute in the same processor. Any attached shared memory segments are detached from the child process by a successful call to the tdm_fork( ) function when the child process executes in a different processor than that used by the parent. Refer to the

shmat(2) reference page for additional information about shared memory segment use.

Semaphores

Semaphore set IDs attached to a parent process are also attached to the child process if the child process executes in the same processor as the parent.

A semaphore set cannot be shared when a semadj value exists for the parent process and the child process is created in a different processor. When that condition exists, a call to the

tdm_fork( ) function fails and errno is set to [EHLDSEM].

Refer to the semget(2) reference page for additional information about semaphore use.

Open Files

File descriptors open in the parent process remain open in the child process, except for those opened using a Guardian function or procedure call. For those file descriptors that remain open, all attributes of the open file descriptor, including file locks, remain unchanged.

Open Pipes and FIFOs

A pipe or FIFO associated with an open file descriptor in the parent process remains connected in the child process. If the child process runs in a different processor than the parent process, the processor that runs the child process must also be running an OSS pipe server process.

If no OSS pipe server process is running in the new processor, the child process cannot use the pipe or FIFO; calls specifying the file descriptor for the pipe or FIFO fail with errno set to

[EWRONGID]. The child process can only close the invalid file descriptor.

Existing Sockets

A socket associated with an open file descriptor in the parent process remains connected in the child process. If the child process runs in a different processor than the parent process, the processor that runs the child process must also be running a socket transport agent process.

If no socket transport agent process is running in the new processor, the child process cannot use the socket; calls specifying the file descriptor for the socket fail with errno set to [EWRONGID].

The child process can only close the invalid file descriptor.

Sharing Guardian Files

After a successful call to the tdm_fork( ) function, the initial position within an open EDIT file

(file code 101) in the Guardian file system (a file in /G) that was opened by a call to the OSS

open( ) function is the same for both the parent and child processes. However, the position is not shared; that is, changing the position used by one process does not change the position used by the other process.

Floating-Point Data

If the parent process uses IEEE floating-point data, the child process inherits all the floating-point register contents of the parent process and any computation that was started before the

tdm_fork( ) function call finishes in the child process. The contents of the status and control register also are inherited.

RETURN VALUES

Upon successful completion, the tdm_fork( ) function returns the value 0 (zero) to the child process and returns the OSS process ID of the child process to the parent process. If the pr_results parameter does not contain a null pointer, it returns the Guardian process handle of the child process in addition to the OSS process ID.

8

38 Hewlett-Packard Company 527186-003

System Functions (t) tdm_fork(2)

If the tdm_fork( ) function fails, the value -1 is returned to the parent process, no child process is created, and errno is set to indicate the error. If pr_results does not contain a null pointer, it returns additional error information including the PROCESS_LAUNCH_ procedure error and error detail.

ERRORS

If any of the following conditions occurs, the tdm_fork( ) function sets errno to the corresponding value:

[EACCES]

[EAGAIN]

[EFAULT] An address for a parameter in the process_extension structture pointed to by

pe_parms is out of allowable bounds. The Guardian PROCESS_LAUNCH_ procedure error and error detail information is returned in the structure pointed to by the pr_results parameter, unless pr_results contains a null pointer.

[EHLDSEM] The process tried to create a child process in a different processor while having at least one semadj value.

[EINVAL]

Open for execute access on the code file or any library file was denied.

System resources such as disk space, process control block (PCB) space, MAP-

POOL space, stack space, or PFS space are temporarily inadequate.

[EIO]

An invalid parameter value was supplied in the process_extension structure pointed to by pe_parms. The Guardian PROCESS_LAUNCH_ error and error detail information is returned in the structure pointed to by the pr_results parameter, unless pr_results contains a null pointer.

Some physical input or output error has occurred. Either a file cannot be opened because of an input or output error or data has been lost during an input or output transfer. This value is used only for errors on the object file of a loaded program or library, or during data transfer with a Guardian environment home terminal.

[ENOMEM] Required resources are not available. Subsequent calls to the same function will not succeed for the same reason.

Possible causes of this error include insufficient primary memory (stack, globals, or heap) for the child process.

[ENOTOSS] The parent process is not an OSS process. The tdm_fork( ) function cannot be used from the Guardian environment.

[EUNKNOWN]

Unknown error. An unrecognized or very obscure error occurred. If this error occurs, follow site-defined procedures for reporting software problems to

HP.

R"ELATED INFORMATION"

Functions: exec(2), _exit(2), fork(2), raise(3), semget(2), semop(2), shmat(2), sigaction(2),

tdm_execve(2), tdm_execvep(2), tdm_spawn(2), tdm_spawnp(2), times(3), ulimit(2),

umask(2), wait(2).

Miscellaneous: process_extension_results(5).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification.

527186-003 Hewlett-Packard Company 8

39

tdm_spawn(2) OSS System Calls Reference Manual

NAME

tdm_spawn - Executes a new process with HP extensions

LIBRARY

G-series native OSS processes: /G/system/sysnn/zossksrl

H-series OSS processes: /G/system/zdllnnn/zosskdll

SYNOPSIS

#include <spawn.h>

#include <tdmext.h>

[ extern char **environ; ]

pid_t tdm_spawn( const char

∗∗

path,

const int fd_count,

const int fd_map[ ],

const struct inheritance

∗∗

inherit,

char

∗∗

const argv[ ],

char

∗∗

const envp[ ],

const struct process_extension

∗∗

pe_parms,

struct process_extension_results

∗∗

pr_results);

PARAMETERS

**environ

path fd_count

fd_map[ ]

inherit

argv[ ]

Points to an array of character pointers to environment strings. The environment strings define the OSS environment for the parent process. The environ array is terminated by a null pointer.

Points to a null-terminated string containing a pathname that identifies the new process image file. The pathname is absolute if it starts with a slash ( / ) character. Otherwise, the pathname is relative and is resolved by prefixing the current working directory.

Specifies the number of file descriptors designated by the fd_map[ ] parameter.

All file descriptors higher than fd_count are closed in the new process. This parameter can take values from 0 (zero) through POSIX_OPEN_MAX.

Maps file descriptors from the parent process to the new process. File descriptors identified with the value SPAWN_FDCLOSED are closed in the new process.

If this parameter is a null pointer, all open OSS file descriptors of the parent process (except for files opened by Guardian function or procedure calls and those with the FD_CLOEXEC attribute flag set) are inherited by the new process.

Such inherited file descriptors behave here as they do for the tdm_execve( ) function.

Points to a structure that allows the process group ID and signal mask of the new process to be specified in addition to a list of signals that the new process will take default action on. The structure is defined in the spawn.h header file.

Specifies an array of character pointers to null-terminated strings containing arguments to be passed to the main function of the new program. argv[0] should point to the null-terminated string containing the filename of the new process image. The last member of this array must be a null pointer.

8

40 Hewlett-Packard Company 527186-003

System Functions (t) tdm_spawn(2)

envp[ ]

pe_parms pr_results

Specifies an array of character pointers to null-terminated strings that describe the environment for the new process.

Points to the input structure containing Guardian process attributes to be assigned to the new process. The structure is defined in the tdmext.h header file.

When this parameter contains a null pointer, the tdm_spawn( ) function assumes default Guardian attributes. Otherwise, the structure must be defined locally and initialized before its first use. Initialization is done using the #define

DEFAULT_PROCESS_EXTENSION, as defined in the tdmext.h header file.

The initialized values can then be modified as appropriate for the call.

Points to the output structure containing optional process identification and error information. In case of error, this structure provides additional information, including the PROCESS_LAUNCH_ procedure error and error detail. The structure is defined in the tdmext.h header file.

The structure must be defined locally and initialized before its first use. Initialization is done by using the #define

DEFAULT_PROCESS_EXTENSION_RESULTS, as defined in the tdmext.h header file.

See the process_extension_results(5) reference page for information about the | content of the structure. The tdmext.h header file is not kept current when new | error codes are defined for process creation functions. The list of _TPC_ macros | described in that reference page is not complete; for a current description of error | macros and error codes, see the Guardian header file

$SYSTEM.ZSPIDEF.ZGRDC or the summary of process-creation errors in the |

|

Guardian Procedure Calls Reference Manual (see the table entitled "Summary | of Process Creation Errors").

|

DESCRIPTION

The tdm_spawn( ) function creates a new process image. The new image is constructed from a regular executable file, called a new process image file. The new process image file is formatted as an executable text or binary file in one of the formats recognized by the tdm_spawn( ) function.

The tdm_spawn( ) function is similar to the tdm_spawnp( ) function. The main difference is the way the pathname for the process image file is resolved. tdm_spawn( ) always resolves relative pathnames by prefixing the current working directory; see Identifying the Process Image File, later in this reference page. tdm_spawnp( ) sometimes uses the PATH environment variable to resolve pathnames.

The tdm_spawn( ) function provides a different way to create a new process than the way provided by the tdm_fork( ) and tdm_execve( ) functions. tdm_spawn( ) provides a more efficient way to create a new process to execute a new program file. However, tdm_spawn( ) does not provide all the function provided by tdm_fork( ) and tdm_execve( ).

When a program is executed as a result of a tdm_spawn( ) call, it is entered as a function call:

int main(

int argc,

char

∗∗

argv[ ],

char

∗∗

envp);

Here, the argc parameter is the argument count, the argv[ ] parameter is an array of character pointers to the arguments themselves, and the envp parameter is a pointer to a character array listing the environment variables. The argv[ ] array is terminated by a null pointer. The null pointer is not counted in argc.

527186-003 Hewlett-Packard Company 8

41

tdm_spawn(2) OSS System Calls Reference Manual

The arguments specified by a program using the tdm_spawn( ) function are passed on to the new process image in the corresponding arguments to the main( ) function.

Use From the Guardian Environment

If called from a Guardian process, the actions of this function are undefined, and errno is set to

[ENOTOSS].

Identifying the Process Image File

The tdm_spawn( ) function uses the path parameter to identify the process image file. This parameter points to the absolute pathname if the pathname starts with a slash ( / ) character. Otherwise, the pathname is relative and is resolved by prefixing the current working directory.

Passing the Arguments

The argv[ ] parameter is an array of character pointers to null-terminated strings. The last member of this array is a null pointer. These strings constitute the argument list available to the new process image. The value in argv[0] should point to a filename that is associated with the process being started by the tdm_spawn( ) function.

Specifying the Environment

The envp[ ] parameter is an array of character pointers to null-terminated strings. These strings constitute the environment for the new process image. The environment array is terminated with a null pointer.

The number of bytes available for the new process’s combined argument and environment lists has a system-imposed limit. This limit, which includes the pointers and the null terminators on the strings, is available by calling the sysconf(_SC_ARG_MAX) function.

Executing a Binary File

If the file specified as the new process image file is a binary executable file, the tdm_spawn( ) function loads the file directly.

Executing a Text File

If the file specified as the new process image file is not a binary executable file, the

tdm_spawn( ) function examines the file to determine whether it is an executable text file. It checks for a header line in this format:

#! interpreter_name [optional_string]

The #! notation identifies the file as an executable text file. The new process image filename is constructed from the process image filename in the interpreter_name string, treating it like the

path parameter. The Guardian input and output structures pointed to by the pe_parms and

pr_results parameters apply to the command interpreter as they would to any process file.

The arguments passed to the new process are modified as listed:

argv[0] is set to the name of the command interpreter.

If the optional_string portion is present, argv[1] is set to optional_string.

The next element of argv[ ] is set to the original value of path.

The remaining elements of argv[ ] are set to the original elements of argv[ ], starting with

argv[1]. The original argv[0] is discarded.

The S_ISUID and S_ISGID mode bits of an executable text file are ignored.

8

42 Hewlett-Packard Company 527186-003

System Functions (t) tdm_spawn(2)

When the File Is Invalid

If the process image file is not a valid executable object, or if the text file does not contain the header line, the tdm_spawn( ) function returns and sets errno to [ENOEXEC].

Open Files

The fd_count and fd_map[ ] parameters determine which file descriptors that were open in the calling process remain open in the new process.

fd_count specifies the number of file descriptors to be designated by the fd_map[ ] parameter.

fd_map[ ] specifies how file descriptors in the parent process map to file descriptors in the new process. That is, the file descriptor in fd_map[0] is copied to file descriptor 0 (zero) in the new process, the file descriptor in fd_map[1] is copied to file descriptor 1 in the new process, and so on. If fd_map[ ] has a null value, the fd_count parameter is ignored and all open file descriptors in the parent (except for files opened by Guardian function or procedure calls and those with the

FD_CLOEXEC attribute flag set) are inherited without mapping by the new process. Such inherited file descriptors behave here as they do for the tdm_execve( ) function.

If fd_map[ ] does not have a null value, file descriptors from fd_count to OPEN_MAX are closed in the new process, as are entries in fd_map[ ] that are identified with the value

SPAWN_FDCLOSED.

If a file descriptor specified in fd_map[ ] is invalid, the function call fails. (Any file descriptor created by a Guardian function or procedure call is invalid.) The errno variable is set to

[EBADF].

For a G-series TNS process image or an accelerated process image only, if the process file segment (PFS) of the new process image is smaller than the process file segment of the calling process image and if the calling process image has a large number of file descriptors open, then the system might not be able to propagate all the open file descriptors to the new process image.

When this situation occurs, the function call fails, and errno is set to the value of [EMFILE].

Open Pipes and FIFOs

A pipe or FIFO associated with an open file descriptor in the parent process remains connected in the child process. If the child process runs in a different processor than the parent process, the processor that runs the child process must also be running an OSS pipe server process.

If no OSS pipe server process is running in the new processor, the child process cannot use the pipe or FIFO; calls specifying the file descriptor for the pipe or FIFO fail with errno set to

[EWRONGID]. The child process can only close the invalid file descriptor.

Existing Sockets

A socket associated with an open file descriptor in the calling process remains connected in the new process when the new process runs in the same processor as the calling process.

When the new process runs in a different processor than the calling process, the processor that runs the new process must also be running a socket transport agent process. If no socket transport agent process is running in the new processor, the new process cannot use the socket; calls specifying the file descriptor for the socket fail with errno set to [EWRONGID]. The new process can only close the invalid file descriptor.

Sharing Guardian Files

After a successful call to the tdm_spawn( ) function, the initial position within an open EDIT file

(file code 101) in the Guardian file system (a file in /G) that was opened by a call to the OSS

open( ) function is the same for both the parent and child processes. However, the position is not shared; that is, changing the position used by one process does not change the position used by the other process.

527186-003 Hewlett-Packard Company 8

43

tdm_spawn(2) OSS System Calls Reference Manual

Shared Memory

Any attached shared memory segments are detached from the child process by a successful call to the tdm_spawn( ) function. See the shmat(2) reference page for additional information about shared memory segment use.

Semaphores

Semaphore set IDs attached to a parent process are also attached to the child process if the child process executes in the same processor as the parent.

A semaphore set cannot be shared when a semadj value exists for the parent process and the child process is created in a different processor. When that condition exists, a call to the

tdm_spawn( ) function fails and errno is set to [EHLDSEM].

See the semget(2) reference page for additional information about semaphore use.

Signals

The setting of signaling attributes in the new process depends on the information provided in the

inheritance structure (pointed to by the inherit parameter).

This default signal information applies to the child process unless modified by the information in the inheritance structure:

Signals set to the default action (SIG_DFL) in the parent process are set to the default action in the child process.

Signals set to be ignored (SIG_IGN) by the parent process are set to be ignored by the child process.

Signals that cause abnormal termination (SIG_ABORT) in the calling process image are | set to that action in the new process image.

Signals that cause entry into the debugger (SIG_DEBUG) in the calling process image | are set to that action in the new process image.

Signals set to be caught by the parent process are set to the default action in the child process (see the signal(4) reference page).

The signal mask in the child process is inherited from the parent process.

Signals pending in the parent process are disregarded by the child process.

The inheritance structure can modify the default signal information as listed:

If the SPAWN_SETSIGMASK bit is set in

inherit->flags, then inherit->sigmask contains the signal mask for the child process.

If the SPAWN_SETSIGDEF bit is set in

inherit->flags, then inherit->sigdefault specifies the signal set that is forced to the default action in the child process. Additional signals that are set to the default action in the parent process, or for which the parent process has a signal-catching function installed, are also set to the default action in the child process.

Process Group

By default, the child process is a member of the same process group as the parent. However, the new process can be designated a member of some other process group by setting the

SPAWN_SETPGROUP bit in inherit->flags. The inherit->pgroup field specifies the process group number, or it contains the SPAWN_NEWPGROUP symbolic constant if the new process is to be the leader of a new process group.

8

44 Hewlett-Packard Company 527186-003

System Functions (t) tdm_spawn(2)

User ID and Group ID

If the set-user-ID mode bit (S_ISUID) of the new process image file is set (see the chmod(2) reference page), the effective user ID of the new process image is set to the user ID of the owner of the new process image file. Similarly, if the set-group-ID mode bit (S_ISGID) of the new process image file is set, the effective group ID of the new process image is set to the group ID of the new process image file. The real user ID, real group ID, and supplementary group IDs of the new process image remain the same as those of the calling process image. The effective user ID and effective group ID of the new process image are saved (as the saved-set user ID and the saved-set group ID) for use by the setuid( ) function.

OSS Attributes

These OSS attributes of the calling process image are unchanged after successful completion of the tdm_spawn( ) function:

Real user ID

Real group ID

Session membership

Current working directory

Root directory

File mode creation mask (see the umask(2) reference page)

File size limit (see the ulimit(2) reference page)

The OSS attributes of the child process differ from those of the parent process in these ways:

The child process has a unique OSS process ID (PID) and does not match any active process group ID.

The parent process ID of the child process matches the OSS process ID of the parent.

The child process has its own copy of a subset of the parent process’s file descriptors.

See Open Files, earlier in this reference page. However, each of the child’s file descriptors shares a common file pointer with the corresponding file descriptor of the parent process.

The child process does not inherit file opens created by Guardian function or procedure calls.

The child process does not inherit file locks.

The child process’s tms_utime, tms_stime, tms_cutime, and tms_cstime values are set to 0 (zero).

Any pending alarms are cleared in the child process.

Any adjust-on-exit (semadj) values of the parent process are not inherited by the child process.

Any signals pending for the parent process are not inherited by the child process.

The signal mask of the child process is that of the parent process unless modified by the

inherit->sigmask field. See Signals, earlier in this reference page.

527186-003 Hewlett-Packard Company 8

45

tdm_spawn(2) OSS System Calls Reference Manual

The set of signals for which default action is set and the set of signals to be ignored are the same in the child process as in the parent process unless modified by

inherit->sigdefault. See Signals, earlier.

The child process does not share directory streams with the parent. All open directory streams are closed for the child process.

Default Guardian Attributes

If the pe_parms parameter contains a null pointer, the newly created OSS process retains all of these default Guardian attributes of the process that calls the tdm_spawn( ) function:

Priority

Processor on which the process executes

Home terminal

Job ID

DEFINE mode switch

Creator access ID (CAID)

Process access ID (PAID), unless the S_ISUID mode bit of the new process image file is set

Security group list

Job ancestor or GMOM

Unread system message index (PCBMCNT)

This attribute assignment is different from the assignment made when creating a new process with Guardian procedures.

Outstanding incoming and outgoing message limits

This attribute assignment is different from the assignment made when creating a new process with Guardian procedures.

Login, remote login, and saveabend flags

File creation mask

If the pe_parms parameter contains a null pointer, the default Guardian attributes of the new process that differ from those of the calling process are:

Segments created or shared using Guardian procedures such as

SEGMENT_ALLOCATE_ are not inherited.

The program file is the file specified in the tdm_spawn( ) call.

The library file is specified in the program file.

The child process does not inherit the parent process extended swap file (if any). For a

G-series TNS process or an accelerated process, the extended data segment is managed by the Kernel Managed Storage Facility (KMSF) unless an extended swap file is specified in the pe_extwap_file_name field of the process_extension structure described elsewhere in this reference page.

8

46 Hewlett-Packard Company 527186-003

System Functions (t) tdm_spawn(2)

The process name for the new process is system-generated if the RUNNAMED option is set in the program file. Otherwise, the process is unnamed.

The size of the data segment of the new process is set in the program file.

The remote login flag (PCBREMID) is set to zero (off) if the program file has its

S_ISUID mode bit set. Otherwise, the remote login flag is set the same as for the caller.

The size of the extended data segment of the new process is set in the program file.

The DEFINEs inherited by the new process depend on the setting of DEFINE mode in the caller. If DEFINE mode in the caller is ON, all the caller’s DEFINEs are inherited. If

DEFINE mode is OFF, no DEFINEs are inherited.

The process identification number (PIN) of the child process is unrelated to that of the parent process. Usually, the PIN of the child process is unrestricted. However, the PIN can be restricted to the range 0 through 254 under the following conditions:

— The HIGHPIN flag is not set in, or is absent from, the program file or any library file.

_TPC_HIGHPIN_OFF is specified in the pe_create_options field of the

process_extension structure, described following.

— The restriction is inherited. See _TPC_IGNORE_FORCEPIN_ATTR in the

pe_create_options field of the process_extension structure, described following, for more information about controlling inheritance.

The process access ID (PAID) depends on whether the S_ISUID mode bit of the process image file is set. If that bit is set, the PAID is based on the file owner ID. If not, the PAID is the same as for the caller. (The S_ISUID mode bit of the image file has no effect on the security group list.)

For unnamed processes, the MOM field of the child process is NULL. For named processes, the ancestor field identifies the parent.

System debugger selection for the new process is based on the INSPECT mode of the program file.

Code breakpoints and memory breakpoints are not inherited.

For detailed information about Guardian process attributes, see the PROCESS_LAUNCH_ procedure in the Guardian Procedure Calls Reference Manual.

Setting Guardian Attributes

The input structure pointed to by the pe_parms parameter permits the setting of Guardian attributes for the new process.

First, the input structure must be initialized to the default values (see Default Guardian Attri-

butes, earlier in this reference page) using the #define DEFAULT_PROCESS_EXTENSION.

After the structure is initialized, the values can be set using literals that are defined in the

tdmext.h header file.

If any optional parameter specified in the structure pointed to by pe_parms is not passed, the new process assumes the corresponding default value.

The input structure is defined in the tdmext.h header file. This structure can contain fields that vary from release version update (RVU) to RVU, including reserved and filler fields.

527186-003 Hewlett-Packard Company 8

47

tdm_spawn(2) OSS System Calls Reference Manual

In the current RVU, these fields are meaningful:

typedef struct process_extension { long pe_len; char *pe_library_name; char *pe_swap_file_name; char *pe_extswap_file_name; short pe_priority; short pe_cpu; short pe_name_options; char filler_1[2]; char *pe_process_name; char *pe_hometerm; short pe_memory_pages; short pe_jobid; short pe_create_options; char filler_2[2]; char *pe_defines; short pe_defines_len; short pe_debug_options; long pe_pfs_size; short pe_OSS_options; char filler_3[2]; long pe_mainstack_max; long pe_heap_max; long pe_space_guarantee;

} process_extension_def;

The input structure passes this information:

pe_len

Specifies the size of the structure in bytes. This value is set by #define

DEFAULT_PROCESS_EXTENSION and should not be changed.

pe_library_name

Points to the name of the user library to be bound to the new process. The string that is pointed to is null-terminated and in OSS pathname format. If the pointer points to a zero-length string (a NULL character), the new process runs without a user library file. An equivalent call to the Guardian PROCESS_LAUNCH_ procedure does this by setting the library filename length to -1.

This field is used only for G-series TNS or accelerated new process image files.

If a value is specified for this field for native object files, the specified value is ignored.

pe_swap_file_name

Points to a null-terminated string specifying the name of a file in the Guardian file system to be used as the swap file for the stack segment. For example, if the

Guardian filename is $A.B.C, the name used is /G/a/b/c.

This field is not used in the current RVU of Open System Services. It exists for compatibility with older RVUs. Any specified value is checked for validity but otherwise ignored.

8

48 Hewlett-Packard Company 527186-003

System Functions (t) tdm_spawn(2) pe_extswap_file_name

Points to a null-terminated string specifying the name of a disk file in the Guardian file system to be used as the swap file for the extended data segment. For example, if the Guardian filename is $A.B.D, the name used is /G/a/b/d.

This field is used only for G-series TNS or accelerated new process image files.

If a value is specified for this field for native object files, the specified value is validated but otherwise ignored.

By default, the new process uses KMSF to manage its extended swap segment.

HP recommends using the default.

pe_priority

Specifies the priority of the new process.

pe_cpu

Specifies the processor on which the new process will execute. The OSS process

ID (PID) of the process remains unchanged. This field is used to distribute system load.

pe_name_options

Specifies process naming as:

_TPC_GENERATE_NAME

The system generates the name.

_TPC_NAME_SUPPLIED

The process name is indicated by the pe_process_name field.

_TPC_NO_NAME

The new process is unnamed.

pe_process_name

Points to the null-terminated Guardian process name if

_TPC_NAME_SUPPLIED is specified in the pe_name_options field. For example, if the Guardian process name is $DELM, the name used is /G/delm.

pe_hometerm Points to the null-terminated name in the Guardian file system for the home terminal. For example, if the Guardian name is $ztnt.#xyz, the name used is

/G/ztnt/#xyz.

pe_memory_pages

Specifies the size of the data stack in 2 KB units. This field is used only for Gseries TNS or accelerated new process image files. If a value is specified for this field for native object files, the specified value is checked for validity but otherwise ignored.

pe_jobid

Specifies the job ID of the new process.

pe_create_options

Specifies process creation options as:

_TPC_BOTH_DEFINES

Propagates the current DEFINEs and the DEFINEs indicated in the input structure.

_TPC_ENABLE_DEFINES

Enables DEFINEs when set if

_TPC_OVERRIDE_DEFMODE is also set. Disables

DEFINEs when not set.

527186-003 Hewlett-Packard Company 8

49

tdm_spawn(2) OSS System Calls Reference Manual pe_defines

_TPC_HIGHPIN_OFF

Restricts the new process to a PIN in the range 0 through 254.

This restriction is rarely useful for an OSS process; it allows obsolescent Guardian interfaces to interact with the process.

By default, this restriction is inherited by any child or successor process. The default can be overridden by using the

_TPC_IGNORE_FORCEPIN_ATTR field.

_TPC_IGNORE_FORCEPIN_ATTR

Ignores the _TPC_HIGHPIN_OFF restriction specified for or inherited by the caller or parent process. When

_TPC_IGNORE_FORCEPIN_ATTR is specified, the resulting process has a restricted PIN only if _TPC_HIGHPIN_OFF is also specified or if the object file for the program or a user library lacks the HIGHPIN attribute.

_TPC_OVERRIDE_DEFMODE

Specifies that the DEFINE mode of the new process is to be set according to the _TPC_ENABLE_DEFINES option rather than to the caller’s current DEFINE mode.

_TPC_PROCESS_DEFINES_ONLY

Propagates only the current set of DEFINEs.

_TPC_SUPPLIED_DEFINES_ONLY

Propagates only the DEFINEs indicated by the pe_defines field.

Points to a specified saved set of DEFINEs created by using the Guardian

DEFINESAVE procedure. These DEFINEs are propagated to the new process if either _TPC_SUPPLIED_DEFINES_ONLY or _TPC_BOTH_DEFINES is specified in the pe_create_options field.

Note: This string is not null-terminated.

pe_defines_len

Specifies the length of the string in the pe_defines field.

pe_debug_options

Provides control over the selection between the default and symbolic debuggers and over the creation of the saveabend file. A saveabend file can be examined by using a symbolic debugger to determine the cause of the abnormal termination.

In addition, you can use this option to force the process to enter the default debugger before executing.

Possible options are:

_TPC_CODEFILE_INSPECT_SAVEABEND

Uses the saveabend flag and the INSPECT mode flag in the program file.

_TPC_DEBUG_NOSAVE

Uses the default debugger but does not create a saveabend file.

8

50 Hewlett-Packard Company 527186-003

System Functions (t) tdm_spawn(2)

_TPC_DEBUG_SAVEABEND

Uses the default debugger and creates a saveabend file.

_TPC_ENTER_DEBUG

Starts the new process in the default debugger.

_TPC_INSPECT_NOSAVE

Uses the symbolic debugger but does not create a saveabend file.

_TPC_INSPECT_SAVEABEND

Uses the symbolic debugger and creates a saveabend file.

pe_pfs_size

Specifies the size of the process file segment (PFS) for the new process (this field is ignored).

pe_OSS_options

Specifies OSS options. No special action on signals is the default and only current OSS option.

pe_mainstack_max

Specifies the maximum size of the main stack in bytes for the new process.

If the calling process specifies a value, the value must be less than 32 MB. If the calling process does not specify a value or specifies a 0 (zero) value, the value specified in the object file of the new process is used. If no value is specified in the object file, the default value of 1 MB (for TNS/R systems) or 2 MB (for

TNS/E systems) is used.

pe_heap_max Specifies the maximum size of the heap in bytes for the new process if it is a native process.

See the C/C++ Programmer’s Guide description of the HEAP pragma for guidance on the use of nonzero values for this field.

If a value is specified for this field for G-series TNS or accelerated object files, the specified value is ignored.

pe_space_guarantee

Specifies the minimum available swap space to guarantee for the new process.

If the calling process specifies a value, the value must be less than or equal to a multiple of the page size of the processor in which the new process will run.

Values less than a multiple of the page size are rounded up to the next multiple of the page size. If the parent process specifies a nonzero value, that value is used for the child process; otherwise, the child process inherits the space guaran|

| tee attribute of the parent process.

If the new process requires a guarantee of available swap space and the system cannot guarantee the required amount, the function call fails, and errno is set to the value of [EAGAIN].

If a value is specified for this field for G-series TNS or accelerated object files, the specified value is used for the main stack of the new process.

For detailed information about Guardian process attributes, see the PROCESS_LAUNCH_ procedure in the Guardian Procedure Calls Reference Manual.

527186-003 Hewlett-Packard Company 8

51

tdm_spawn(2) OSS System Calls Reference Manual

Output Structure Information

If the pr_results parameter does not contain a null pointer, it points to an output structure defined in the tdmext.h header file. This structure can contain fields that vary from RVU to RVU, including reserved and filler fields.

First, the output structure must be initialized by using the #define

DEFAULT_PROCESS_EXTENSION_RESULTS. This initialization sets the value of the

pr_len field to the correct value for the current RVU. The value of the pr_len field should not be modified after being set by #define DEFAULT_PROCESS_EXTENSION_RESULTS.

The process_extension_results output structure is described in the

process_extension_results(5) reference page.

EXAMPLES

This example uses the tdm_spawn( ) function to perform I/O redirection in a new process: if ((NewStdOut = open ("newout", ...)) != -1)

/* process the error */ fd_map[0] = 0; fd_map[1] = NewStdOut; fd_map[2] = 2; fd_count = 3; tdm_spawn(..., fd_count, fd_map, ...); close(NewStdOut);

This example creates a new process under a different user ID: save = getuid(); setuid(newid); tdm_spawn(...); setuid(save);

RETURN VALUES

Upon successful completion, the tdm_spawn( ) function returns the OSS process ID of the child process to the parent process. If the pr_results parameter does not contain a null pointer, it returns the Guardian process handle of the new process in addition to the OSS process ID.

If the tdm_spawn( ) function fails, the value -1 is returned to the parent process, no child process is created, and errno is set to indicate the error. If the pr_results parameter does not contain a null pointer, the structure it points to returns additional error information, including the

PROCESS_LAUNCH_ error and error detail.

ERRORS

If any of the following conditions occurs, the tdm_spawn( ) function sets errno to the corresponding value, file descriptors marked close-on-exec are not closed, signals set to be caught are not set to the default action, and none of these are changed:

The argv[ ] array of pointers

The envp[ ] array of pointers

The elements pointed to by these arrays

The value of the global variable environ

8

52 Hewlett-Packard Company 527186-003

System Functions (t) tdm_spawn(2)

The pointers contained within the global variable environ

The elements pointed to by environ pointers

The effective user ID of the current process

The effective group ID of the current process

[E2BIG]

[EACCES]

The number of bytes used by the new process image’s argument list and environment list is greater than the system-imposed limit. The limit can be obtained by calling the sysconf(_SC_ARG_MAX) function.

One of these conditions exists:

Search permission is denied for the directory components of the pathname prefix to the process image file.

The new process image file, any library file, or script file denies execution permission.

Create access on the extended swap file on a disk under Safeguard protection is denied.

This error occurs only for G-series TNS or accelerated new process image files.

The new process image file is not a regular file.

[EAGAIN]

[EBADF]

[EFAULT]

System resources such as disk space, process control block (PCB) space, MAP-

POOL space, stack space, or PFS space are temporarily inadequate.

A file descriptor pointed to by the fd_map[ ] parameter is invalid.

An address for a parameter in the process_extension structure pointed to by

pe_parms is out of allowable bounds. The Guardian PROCESS_LAUNCH_ error and error detail information is returned in the structure pointed to by the

pr_results parameter, unless pr_results contains a null pointer.

[EHLDSEM] The process tried to create a child process in a different processor while having at least one semadj value.

[EINVAL] One of these conditions exists:

An invalid parameter value was supplied in the process_extension structure pointed to by pe_parms. The Guardian PROCESS_LAUNCH_ error and error detail information is returned in the structure pointed to by the pr_results parameter, unless pr_results contains a null pointer.

The new process image file is a binary executable file with invalid attributes.

[EIO] Some physical input or output error has occurred. Either a file cannot be opened because of an input or output error or data has been lost during an input or output transfer. This value is used only for errors on the object file of a loaded program or library, or during data transfer with a Guardian environment home terminal.

527186-003 Hewlett-Packard Company 8

53

tdm_spawn(2) OSS System Calls Reference Manual

[ELOOP]

[EMFILE]

Too many symbolic links were encountered in pathname resolution.

The maximum number of files are open. The process attempted to open more than the maximum number of file descriptors allowed for the process. One of these conditions might exist:

The maximum value for fd_count has been exceeded.

The process file segment (PFS) of the child process is smaller than that of the parent process.

[ENAMETOOLONG]

One of these is too long:

The pathname pointed to by the path parameter

A component of the pathname pointed to by the path parameter

The intermediate result of pathname resolution when a symbolic link is part of the pathname pointed to by the path parameter

The pathconf( ) function can be called to obtain the applicable limits.

[ENOCPU] The selected processor does not exist, or the selected processor is down or otherwise unavailable for process creation.

[ENODEV] The system cannot find the fileset containing the process image file.

[ENOENT] One of these conditions exists:

One or more components of the new process image file’s pathname do not exist.

The path parameter points to an empty string.

[ENOEXEC] The new process image file has the appropriate access permissions and is in the

OSS name space, but it is neither in the correct binary executable format nor a valid executable text file.

[ENOMEM] Required resources are not available. Subsequent calls to the same function will not succeed for the same reason.

Possible causes of this error include insufficient primary memory (stack, globals, or heap) for the new process.

[ENOTDIR] A component of the path prefix of the new process image file is not a directory.

[ENOTOSS] The calling process is not an OSS process. The tdm_spawn( ) function cannot be used from the Guardian environment.

[EPERM] The value of the inherit->pgroup field does not match any process group ID in the same session as the calling process.

[ETXTBSY] The new process image file is a pure procedure (shared text) file that is currently open for writing by some process.

8

54 Hewlett-Packard Company 527186-003

System Functions (t) tdm_spawn(2)

[EUNKNOWN]

Unknown error. An unrecognized or very obscure error occurred. If this error occurs, follow site-defined procedures for reporting software problems to

HP.

The structure pointed to by the pr_results parameter might contain additional Guardian

PROCESS_LAUNCH_ procedure error and error detail information if any of these errors occur:

[EACCES], [EAGAIN], [EFAULT], [EINVAL], [EIO], [ENOCPU], and [ENOEXEC].

RELATED INFORMATION

Commands: eld(1), ld(1), nld(1).

Functions: alarm(3), chmod(2), exec(2), _exit(2), exit(3), fcntl(2), fork(2), getenv(3),

putenv(3), semget(2), shmat(2), sigaction(2), system(3), tdm_execve(2), tdm_execvep(2),

tdm_fork(2), tdm_spawnp(2), times(3), ulimit(2), umask(2).

Files: signal(4).

Miscellaneous: environ(5), process_extension_results(5).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification.

527186-003 Hewlett-Packard Company 8

55

tdm_spawnp(2) OSS System Calls Reference Manual

NAME

tdm_spawnp - Executes a new process with HP extensions

LIBRARY

G-series native OSS processes: /G/system/sysnn/zossksrl

H-series OSS processes: /G/system/zdllnnn/zosskdll

SYNOPSIS

#include <spawn.h>

#include <tdmext.h>

[ extern char **environ; ]

pid_t tdm_spawnp( const char

∗∗

file,

const int fd_count,

const int fd_map[ ],

const struct inheritance

∗∗

inherit,

char

∗∗

const argv[ ],

char

∗∗

const envp[ ],

const struct process_extension

∗∗

pe_parms,

struct process_extension_results

∗∗

pr_results);

PARAMETERS

**environ

file

Points to an array of character pointers to environment strings. The environment strings define the OSS environment for the parent process. The environ array is terminated by a null pointer.

Points to a pathname that identifies the new process image file. If the pathname:

Starts with a slash ( / ) character; it is the absolute pathname.

Does not start with a slash but does contain a slash; the pathname resolves relative to the current working directory.

Contains no slash, the system searches the directories listed in the PATH environment variable for the file and prefixes the directory in which the file is found.

fd_count

fd_map[ ]

Specifies the number of file descriptors designated by the fd_map[ ] parameter.

All file descriptors higher than fd_count are closed in the child process. This parameter can take values from 0 (zero) through POSIX_OPEN_MAX.

Maps file descriptors from the parent process to the child process. File descriptors identified with the value SPAWN_FDCLOSED are closed in the child process.

If this parameter is a null pointer, all open OSS file descriptors of the parent process (except for files opened by Guardian function or procedure calls and those with the FD_CLOEXEC attribute flag set) are inherited by the child process.

Such inherited file descriptors behave here as they do for the tdm_execvep( ) function.

8

56 Hewlett-Packard Company 527186-003

System Functions (t) tdm_spawnp(2)

inherit

argv[ ]

envp[ ]

pe_parms pr_results

Points to a structure that allows the process group ID and signal mask of the new process to be specified in addition to a list of signals that the child process will take default action on. The structure is defined in the spawn.h header file.

Specifies an array of character pointers to null-terminated strings containing arguments to be passed to the main function of the new program. argv[0] should point to the null-terminated string containing the filename of the new process image. The last member of this array must be a null pointer.

Specifies an array of character pointers to null-terminated strings that describe the environment for the new process.

Points to the input structure containing Guardian process attributes to be assigned to the new process. The structure is defined in the tdmext.h header file.

When this parameter contains a null pointer, the tdm_spawnp( ) function assumes default Guardian attributes. Otherwise, the structure must be defined locally and initialized before its first use. Initialization is done using the #define

DEFAULT_PROCESS_EXTENSION, as defined in the tdmext.h header file.

The initialized values can then be modified as appropriate for the call.

Points to the output structure containing optional process identification and error information. In case of error, this structure provides additional information, including the PROCESS_LAUNCH_ procedure error and error detail. The structure is defined in the tdmext.h header file.

The structure must be defined locally and initialized before its first use. Initialization is done by using the #define

DEFAULT_PROCESS_EXTENSION_RESULTS, as defined in the tdmext.h header file.

See the process_extension_results(5) reference page for information about the | content of the structure. The tdmext.h header file is not kept current when new | error codes are defined for process creation functions. The list of _TPC_ macros | described in that reference page is not complete; for a current description of error | macros and error codes, see the Guardian header file

$SYSTEM.ZSPIDEF.ZGRDC or the summary of process-creation errors in the |

|

Guardian Procedure Calls Reference Manual (see the table entitled "Summary | of Process Creation Errors").

|

DESCRIPTION

The tdm_spawnp( ) function creates a new process image. The new image is constructed from a regular executable file, called a new process image file. The new process image file is formatted as an executable text or binary file in one of the formats recognized by the tdm_spawnp( ) function.

The tdm_spawnp( ) function is similar to the tdm_spawn( ) function. The main difference is the way the pathname for the process image file is resolved. tdm_spawn( ) always resolves relative pathnames by prefixing the current working directory. tdm_spawnp( ) sometimes uses the

PATH environment variable to resolve pathnames; see Identifying the Process Image File, later in this reference page.

The tdm_spawnp( ) function provides a different way to create a new process than the way provided by the tdm_fork( ) and tdm_execvep( ) functions. tdm_spawnp( ) provides a more efficient way to create a new process to execute a new program file. However, tdm_spawnp( ) does not provide all the function provided by tdm_fork( ) and tdm_execvep( ).

527186-003 Hewlett-Packard Company 8

57

tdm_spawnp(2) OSS System Calls Reference Manual

When a program is executed as a result of a tdm_spawnp( ) call, it is entered as a function call:

int main(

int argc,

char

∗∗

argv[ ],

char

∗∗

envp);

Here, the argc parameter is the argument count, the argv[ ] parameter is an array of character pointers to the arguments themselves, and the envp parameter is a pointer to a character array listing the environment variables. The argv[ ] array is terminated by a null pointer. The null pointer is not counted in argc.

The arguments specified by a program using the tdm_spawnp( ) function are passed on to the new process image in the corresponding arguments to the main( ) function.

Use From the Guardian Environment

If called from a Guardian process, the actions of this function are undefined, and errno is set to

[ENOTOSS].

Identifying the Process Image File

The tdm_spawnp( ) function uses the file parameter to identify the process image file. If the pathname pointed to by the file parameter starts with a slash ( / ) character, it is the absolute pathname. If the pathname does not start with a slash but contains a slash, the pathname is resolved relative to the current working directory. Otherwise, the pathname does not contain a slash; the system searches the directories listed in the PATH environment variable for the file and prefixes the directory in which the file is found.

Passing the Arguments

The argv[ ] parameter is an array of character pointers to null-terminated strings. The last member of this array is a null pointer. These strings constitute the argument list available to the new process image. The value in argv[0] should point to a filename that is associated with the process being started by the tdm_spawnp( ) function.

Specifying the Environment

The envp[ ] parameter is an array of character pointers to null-terminated strings. These strings constitute the environment for the new process image. The environment array is terminated with a null pointer.

The number of bytes available for the new process’s combined argument and environment lists has a system-imposed limit. This limit, which includes the pointers and the null terminators on the strings, is available by calling the sysconf(_SC_ARG_MAX) function.

Executing a Binary File

If the file specified as the new process image file is a binary executable file, the tdm_spawnp( ) function loads the file directly.

Executing a Text File

If the file specified as the new process image file is not a binary executable file, the

tdm_spawnp( ) function examines the file to determine whether it is an executable text file. It checks for a header line in this format:

#! interpreter_name [optional_string]

The #! notation identifies the file as an executable text file. The new process image filename is constructed from the process image filename in the interpreter_name string, treating it like the

file parameter. The Guardian input and output structures pointed to by the pe_parms and

pr_results parameters apply to the command interpreter as they would to any process file.

The arguments passed to the new process are modified as listed:

8

58 Hewlett-Packard Company 527186-003

System Functions (t) tdm_spawnp(2)

argv[0] is set to the name of the command interpreter.

If the optional_string portion is present, argv[1] is set to optional_string.

The next element of argv[ ] is set to the original value of file.

The remaining elements of argv[ ] are set to the original elements of argv[ ], starting with

argv[1]. The original argv[0] is discarded.

The S_ISUID and S_ISGID mode bits of an executable text file are ignored.

When the File Is Invalid

If the process image file is not a valid executable object, and it is a regular text file that does not contain the header line, the tdm_spawnp( ) function invokes the interpreter_name command interpreter as the new process image and passes these arguments to it:

argv[0] is set to the string "sh".

argv[1] is set to the original value of the file parameter.

The remaining elements of argv[ ] are set to the original elements of argv[ ] starting with

argv[1].

The original argv[0] is discarded.

Open Files

The fd_count and fd_map[ ] parameters determine which file descriptors that were open in the calling process remain open in the child process.

fd_count specifies the number of file descriptors to be designated by the fd_map[ ] parameter.

fd_map[ ] specifies how file descriptors in the parent process map to file descriptors in the child process. That is, the file descriptor in fd_map[0] is copied to file descriptor 0 (zero) in the child process, the file descriptor in fd_map[1] is copied to file descriptor 1 in the child process, and so on. If fd_map[ ] has a null value, the fd_count parameter is ignored and all open file descriptors in the parent (except for files opened by Guardian function or procedure calls and those with the

FD_CLOEXEC attribute flag set) are inherited without mapping by the child process. Such inherited file descriptors behave here as they do for the tdm_execvep( ) function.

If fd_map[ ] does not have a null value, file descriptors from fd_count to OPEN_MAX are closed in the child process, as are entries in fd_map[ ] that are identified with the value

SPAWN_FDCLOSED.

If a file descriptor specified in fd_map[ ] is invalid, the function call fails. (Any file descriptor created by a Guardian function or procedure call is invalid.) The errno variable is set to

[EBADF].

For a G-series TNS process image or an accelerated process image, if the process file segment

(PFS) of the new process image is smaller than the process file segment of the calling process image and if the calling process image has a large number of file descriptors open, then the system might not be able to propagate all the open file descriptors to the new process image. When this situation occurs, the function call fails, and errno is set to the value of [EMFILE].

Open Pipes and FIFOs

A pipe or FIFO associated with an open file descriptor in the parent process remains connected in the child process. If the child process runs in a different processor than the parent process, the processor that runs the child process must also be running an OSS pipe server process.

If no OSS pipe server process is running in the new processor, the child process cannot use the pipe or FIFO; calls specifying the file descriptor for the pipe or FIFO fail with errno set to

[EWRONGID]. The child process can only close the invalid file descriptor.

527186-003 Hewlett-Packard Company 8

59

tdm_spawnp(2) OSS System Calls Reference Manual

Existing Sockets

A socket associated with an open file descriptor in the calling process remains connected in the new process when the new process runs in the same processor as the calling process.

When the new process runs in a different processor than the calling process, the processor that runs the new process must also be running a socket transport agent process. If no socket transport agent process is running in the new processor, the new process cannot use the socket; calls specifying the file descriptor for the socket fail with errno set to [EWRONGID]. The new process can only close the invalid file descriptor.

Sharing Guardian Files

After a successful call to the tdm_spawnp( ) function, the initial position within an open EDIT file (file code 101) in the Guardian file system (a file in /G) that was opened by a call to the OSS

open( ) function is the same for both the parent and child processes. However, the position is not shared; that is, changing the position used by one process does not change the position used by the other process.

Shared Memory

Any attached shared memory segments are detached from the child process by a successful call to the tdm_spawnp( ) function. See the shmat(2) reference page for additional information about shared memory segment use.

Semaphores

Semaphore set IDs attached to a parent process are also attached to the child process if the child process executes in the same processor as the parent.

A semaphore set cannot be shared when a semadj value exists for the parent process and the child process is created in a different processor. When that condition exists, a call to the

tdm_spawnp( ) function fails and errno is set to [EHLDSEM].

See the semget(2) reference page for additional information about semaphore use.

Signals

The setting of signaling attributes in the new process depends on the information provided in the

inheritance structure (pointed to by the inherit parameter).

This default signal information applies to the child process unless modified by the information in the inheritance structure:

Signals set to the default action (SIG_DFL) in the parent process are set to the default action in the child process.

Signals set to be ignored (SIG_IGN) by the parent process are set to be ignored by the child process.

Signals that cause abnormal termination (SIG_ABORT) in the calling process image are | set to that action in the new process image.

Signals that cause entry into the debugger (SIG_DEBUG) in the calling process image | are set to that action in the new process image.

Signals set to be caught by the parent process are set to the default action in the child process (see the signal(4) reference page).

The signal mask in the child process is inherited from the parent process.

8

60 Hewlett-Packard Company 527186-003

System Functions (t) tdm_spawnp(2)

Signals pending in the parent process are disregarded by the child process.

The inheritance structure can modify the default signal information as follows:

If the SPAWN_SETSIGMASK bit is set in

inherit->flags, inherit->sigmask contains the signal mask for the child process.

If the SPAWN_SETSIGDEF bit is set in

inherit->flags, inherit->sigdefault specifies the signal set that is forced to the default action in the child process. Additional signals that are set to the default action in the parent process, or for which the parent process has a signal-catching function installed, are also set to the default action in the child process.

Process Group

By default, the child process is a member of the same process group as the parent. However, the new process can be designated a member of some other process group by setting the

SPAWN_SETPGROUP bit in inherit->flags. The inherit->pgroup field specifies the process group number, or it contains the SPAWN_NEWPGROUP symbolic constant if the new process is to be the leader of a new process group.

User ID and Group ID

If the set-user-ID mode bit (S_ISUID) of the new process image file is set (see the chmod(2) reference page), the effective user ID of the new process image is set to the user ID of the owner of the new process image file. Similarly, if the set-group-ID mode bit (S_ISGID) of the new process image file is set, the effective group ID of the new process image is set to the group ID of the new process image file. The real user ID, real group ID, and supplementary group IDs of the new process image remain the same as those of the calling process image. The effective user ID and effective group ID of the new process image are saved (as the saved-set user ID and the saved-set group ID) for use by the setuid( ) function.

OSS Attributes

These OSS attributes of the calling process image are unchanged after successful completion of the tdm_spawnp( ) function:

Real user ID

Real group ID

Session membership

Current working directory

Root directory

File mode creation mask (see the umask(2) reference page)

File size limit (see the ulimit(2) reference page)

The OSS attributes of the child process differ from those of the parent process in these ways:

The child process has a unique OSS process ID (PID) and does not match any active process group ID.

The parent process ID of the child process matches the OSS process ID of the parent.

527186-003 Hewlett-Packard Company 8

61

tdm_spawnp(2) OSS System Calls Reference Manual

The child process has its own copy of a subset of the parent process’s file descriptors.

See Open Files, earlier in this reference page. However, each of the child’s file descriptors shares a common file pointer with the corresponding file descriptor of the parent process.

The child process does not inherit file opens created by Guardian function or procedure calls.

The child process does not inherit file locks.

The child process’s tms_utime, tms_stime, tms_cutime, and tms_cstime values are set to 0 (zero).

Any pending alarms are cleared in the child process.

Any adjust-on-exit (semadj) values of the parent process are not inherited by the child process.

Any signals pending for the parent process are not inherited by the child process.

The signal mask of the child process is that of the parent process unless modified by the

inherit->sigmask field. See Signals, earlier in this reference page.

The set of signals for which default action is set and the set of signals to be ignored are the same in the child process as in the parent process unless modified by

inherit->sigdefault. See Signals, earlier.

The child process does not share directory streams with the parent. All open directory streams are closed for the child process.

Default Guardian Attributes

If the pe_parms parameter contains a null pointer, the newly created OSS process retains all of these default Guardian attributes of the process that calls the tdm_spawnp( ) function:

Priority

Processor on which the process executes

Home terminal

Job ID

DEFINE mode switch

Creator access ID (CAID)

Process access ID (PAID), unless the S_ISUID mode bit of the new process image file is set

Security group list

Job ancestor or GMOM

Unread system message index (PCBMCNT)

This attribute assignment is different from the assignment made when creating a new process with Guardian procedures.

8

62 Hewlett-Packard Company 527186-003

System Functions (t) tdm_spawnp(2)

Outstanding incoming and outgoing message limits

This attribute assignment is different from the assignment made when creating a new process with Guardian procedures.

Login, remote login, and saveabend flags

File creation mask

If the pe_parms parameter contains a null pointer, the default Guardian attributes of the new process that differ from those of the calling process are as follows:

Segments created or shared using Guardian procedures such as

SEGMENT_ALLOCATE_ are not inherited.

The program file is the file specified in the tdm_spawnp( ) call.

The library file is specified in the program file.

The child process does not inherit the parent process extended swap file (if any). For a

G-series TNS process or an accelerated process, the extended data segment is managed by the Kernel Managed Storage Facility (KMSF) unless an extended swap file is specified in the pe_extwap_file_name field of the process_extension structure described elsewhere in this reference page.

The process name for the new process is system-generated if the RUNNAMED option is set in the program file. Otherwise, the process is unnamed.

The size of the data segment of the new process is set in the program file.

The remote login flag (PCBREMID) is set to zero (off) if the program file has its

S_ISUID mode bit set. Otherwise, the remote login flag is set the same as for the caller.

The size of the extended data segment of the new process is set in the program file.

The DEFINEs inherited by the new process depend on the setting of DEFINE mode in the caller. If DEFINE mode in the caller is ON, all the caller’s DEFINEs are inherited.

If DEFINE mode is OFF, no DEFINEs are inherited.

The process identification number (PIN) of the child process is unrelated to that of the parent process. Usually, the PIN of the child process is unrestricted. However, the PIN can be restricted to the range 0 through 254 under the following conditions:

— The HIGHPIN flag is not set in, or is absent from, the program file or any library file.

_TPC_HIGHPIN_OFF is specified in the pe_create_options field of the

process_extension structure, described elsewhere in this reference page.

— The restriction is inherited. See _TPC_IGNORE_FORCEPIN_ATTR in the

pe_create_options field of the process_extension structure, described elsewhere in this reference page, for more information about controlling inheritance.

The process access ID (PAID) depends on whether the S_ISUID mode bit of the process image file is set. If that bit is set, the PAID is based on the file owner ID. If not, the PAID is the same as for the caller. (The S_ISUID mode bit of the image file has no effect on the security group list.)

527186-003 Hewlett-Packard Company 8

63

tdm_spawnp(2) OSS System Calls Reference Manual

For unnamed processes, the MOM field of the child process is NULL. For named processes, the ancestor field identifies the parent.

System debugger selection for the new process is based on the INSPECT mode flag in the program file.

Code breakpoints and memory breakpoints are not inherited.

For detailed information about Guardian process attributes, see the PROCESS_LAUNCH_ procedure in the Guardian Procedure Calls Reference Manual.

Setting Guardian Attributes

The input structure pointed to by the pe_parms parameter permits the setting of Guardian attributes for the new process.

First, the input structure must be initialized to the default values (see Default Guardian Attri-

butes, earlier in this reference page) using the #define DEFAULT_PROCESS_EXTENSION.

After the structure is initialized, the values can be set using literals that are defined in the

tdmext.h header file.

If any optional parameter specified in the structure pointed to by pe_parms is not passed, the new process assumes the corresponding default value.

The input structure is defined in the tdmext.h header file. This structure can contain fields that vary from release version update (RVU) to RVU, including reserved and filler fields.

In the current RVU, these fields are meaningful:

typedef struct process_extension { long pe_len; char *pe_library_name; char *pe_swap_file_name; char *pe_extswap_file_name; short pe_priority; short pe_cpu; short pe_name_options; char filler_1[2]; char *pe_process_name; char *pe_hometerm; short pe_memory_pages; short pe_jobid; short pe_create_options; char filler_2[2]; char *pe_defines; short pe_defines_len; short pe_debug_options; long pe_pfs_size; short pe_OSS_options; char filler_3[2]; long pe_mainstack_max; long pe_heap_max; long pe_space_guarantee;

} process_extension_def;

8

64 Hewlett-Packard Company 527186-003

System Functions (t) tdm_spawnp(2)

The input structure passes this information:

pe_len

Specifies the size of the structure in bytes. This value is set by the #define

DEFAULT_PROCESS_EXTENSION and should not be changed.

pe_library_name

Points to the name of the user library to be bound to the new process. The string that is pointed to is null-terminated and in OSS name format. If the pointer points to a zero-length string (a NULL character), the new process is run with no user library file. An equivalent call to the Guardian PROCESS_LAUNCH_ procedure does this by setting the library filename length to -1.

This field is used only for G-series TNS or accelerated new process image files.

If a value is specified for this field for native object files, the specified value is ignored.

pe_swap_file_name

Points to a null-terminated string specifying the name of a file in the Guardian file system to be used as the swap file for the stack segment. For example, if the

Guardian filename is $A.B.C, the name used is /G/a/b/c.

This field is not used in the current RVU of Open System Services. It exists for compatibility with older RVUs. Any specified value is checked for validity but otherwise ignored.

pe_extswap_file_name

Points to a null-terminated string specifying the name of a disk file in the Guardian file system to be used as the swap file for the extended data segment. For example, if the Guardian filename is $A.B.D, the name used is /G/a/b/d.

This field is used only for G-series TNS or accelerated new process image files.

If a value is specified for this field for native object files, the specified value is checked for validity but otherwise ignored.

By default, the new process uses KMSF to manage its extended swap segment.

HP recommends using the default.

pe_priority

Specifies the priority of the new process.

pe_cpu

Specifies the processor on which the new process will execute. The OSS process

ID (PID) of the process remains unchanged. This field is used to distribute system load.

pe_name_options

Specifies process naming as follows:

_TPC_GENERATE_NAME

The system generates the name.

_TPC_NAME_SUPPLIED

The process name is indicated by the pe_process_name field.

_TPC_NO_NAME

The new process is unnamed.

527186-003 Hewlett-Packard Company 8

65

tdm_spawnp(2) OSS System Calls Reference Manual pe_process_name

Points to the null-terminated Guardian process name if

_TPC_NAME_SUPPLIED is specified in the pe_name_options field. For example, if the Guardian process name is $DELM, the name used is /G/delm.

pe_hometerm Points to the null-terminated name in the Guardian file system for the home terminal. For example, if the Guardian name is $ztnt.#xyz, the name used is

/G/ztnt/#xyz.

pe_memory_pages

Specifies the size of the data stack in 2K-byte units. This field is used only for

G-series TNS or accelerated new process image files. If a value is specified for this field for native object files, the specified value is checked for validity but otherwise ignored.

pe_jobid

Specifies the job ID of the new process.

pe_create_options

Specifies process creation options as follows:

_TPC_BOTH_DEFINES

Propagates the current DEFINEs and the DEFINEs indicated in the input structure.

_TPC_ENABLE_DEFINES

Enables DEFINEs when set if

_TPC_OVERRIDE_DEFMODE is also set. Disables

DEFINEs when not set.

_TPC_HIGHPIN_OFF

Restricts the new process to a PIN in the range 0 through 254.

This restriction is rarely useful for an OSS process; it allows obsolescent Guardian interfaces to interact with the process.

By default, this restriction is inherited by any child or successor process. The default can be overridden by using the

_TPC_IGNORE_FORCEPIN_ATTR field.

_TPC_IGNORE_FORCEPIN_ATTR

Ignores the _TPC_HIGHPIN_OFF restriction specified for or inherited by the caller or parent process. When

_TPC_IGNORE_FORCEPIN_ATTR is specified, the resulting process has a restricted PIN only if _TPC_HIGHPIN_OFF is also specified or if the object file for the program or a user library lacks the HIGHPIN attribute.

_TPC_OVERRIDE_DEFMODE

Specifies that the DEFINE mode of the new process is to be set according to the _TPC_ENABLE_DEFINES option rather than to the caller’s current DEFINE mode.

_TPC_PROCESS_DEFINES_ONLY

Propagates only the current set of DEFINEs.

8

66 Hewlett-Packard Company 527186-003

System Functions (t) tdm_spawnp(2) pe_defines

_TPC_SUPPLIED_DEFINES_ONLY

Propagates only the DEFINEs indicated by the pe_defines field.

Points to a specified saved set of DEFINEs created by using the Guardian

DEFINESAVE procedure. These DEFINEs are propagated to the new process if either _TPC_SUPPLIED_DEFINES_ONLY or _TPC_BOTH_DEFINES is specified in the pe_create_options field.

Note: This string is not null-terminated.

pe_defines_len

Specifies the length of the string in the pe_defines field.

pe_debug_options

Provides control over the selection between a symbolic or default debugger and over the creation of the saveabend file. A saveabend file can be examined by using a symbolic debugger to determine the cause of the abnormal termination.

In addition, you can use this option to force the process to enter the default debugger before executing.

Possible options are:

_TPC_CODEFILE_INSPECT_SAVEABEND

Uses the saveabend flag and the INSPECT mode flag in the program file.

_TPC_DEBUG_NOSAVE

Uses the default debugger but does not create a saveabend file.

_TPC_DEBUG_SAVEABEND

Uses the default debugger and creates a saveabend file.

_TPC_ENTER_DEBUG

Starts the new process in the default debugger.

_TPC_INSPECT_NOSAVE

Uses the symbolic debugger but does not create a saveabend file.

_TPC_INSPECT_SAVEABEND

Uses the symbolic debugger and creates a saveabend file.

pe_pfs_size

Specifies the size of the process file segment (PFS) for the new process (this field is ignored).

pe_OSS_options

Specifies OSS options. No special action on signals is the default and only current OSS option.

pe_mainstack_max

Specifies the maximum size of the main stack in bytes for the new process.

If the calling process specifies a value, the value must be less than 32 MB. If the calling process does not specify a value or specifies a 0 (zero) value, the value specified in the object file of the new process is used. If no value is specified in the object file, the default value of 1 MB (for TNS/R systems) or 2 MB (for

TNS/E systems) is used.

527186-003 Hewlett-Packard Company 8

67

tdm_spawnp(2) OSS System Calls Reference Manual

pe_heap_max Specifies the maximum size of the heap in bytes for the new process if it is a native process.

See the C/C++ Programmer’s Guide description of the HEAP pragma for guidance on the use of nonzero values for this field.

If a value is specified for this field for G-series TNS or accelerated object files, the specified value is ignored.

pe_space_guarantee

Specifies the minimum available swap space to guarantee for the new process.

If the calling process specifies a value, the value must be less than or equal to a multiple of the page size of the processor in which the new process will run.

Values less than a multiple of the page size are rounded up to the next multiple of the page size. If the parent process specifies a nonzero value, that value is used for the child process; otherwise, the child process inherits the space guaran|

| tee attribute of the parent process.

If the new process requires a guarantee of available swap space and the system cannot guarantee the required amount, the function call fails, and errno is set to the value of [EAGAIN].

If a value is specified for this field for G-series TNS or accelerated object files, the specified value is used for the main stack of the new process.

For detailed information about Guardian process attributes, see the PROCESS_LAUNCH_ procedure in the Guardian Procedure Calls Reference Manual.

Output Structure Information

If the pr_results parameter does not contain a null pointer, it points to an output structure defined in the tdmext.h header file. This structure can contain fields that vary from RVU to RVU, including reserved and filler fields.

First, the output structure must be initialized by using the #define

DEFAULT_PROCESS_EXTENSION_RESULTS. This initialization sets the value of the

pr_len field to the correct value for the current RVU. The value of the pr_len field should not be modified after being set by #define DEFAULT_PROCESS_EXTENSION_RESULTS.

The process_extension_results output structure is described in the

process_extension_results(5) reference page.

EXAMPLES

This example uses the tdm_spawnp( ) function to perform I/O redirection in a new process: if ((NewStdOut = open ("newout", ...)) != -1)

/* process the error */ fd_map[0] = 0; fd_map[1] = NewStdOut; fd_map[2] = 2; fd_count = 3; tdm_spawnp(..., fd_count, fd_map, ...); close(NewStdOut);

8

68 Hewlett-Packard Company 527186-003

System Functions (t) tdm_spawnp(2)

This example creates a new process under a different user ID: save = getuid(); setuid(newid); tdm_spawnp(...); setuid(save);

RETURN VALUES

Upon successful completion, the tdm_spawnp( ) function returns the OSS process ID of the child process to the parent process. If the pr_results parameter does not contain a null pointer, it returns the Guardian process handle of the new process in addition to the OSS process ID.

If the tdm_spawnp( ) function fails, the value -1 is returned to the parent process, no child process is created, and errno is set to indicate the error. If the pr_results parameter does not contain a null pointer, the structure it points to returns additional error information including the

PROCESS_LAUNCH_ error and error detail.

ERRORS

If any of the following conditions occurs, the tdm_spawnp( ) function sets errno to the corresponding value, file descriptors marked close-on-exec are not closed, signals set to be caught are not set to the default action, and none of these are changed:

The argv[ ] array of pointers

The envp[ ] array of pointers

The elements pointed to by these arrays

The value of the global variable environ

The pointers contained within the global variable environ

The elements pointed to by environ pointers

The effective user ID of the current process

The effective group ID of the current process

[E2BIG]

[EACCES]

The number of bytes used by the new process image’s argument list and environment list is greater than the system-imposed limit. The limit can be obtained by calling the sysconf(_SC_ARG_MAX) function.

One of these conditions exists:

Search permission is denied for the directory components of the pathname prefix to the process image file.

The new process image file, any library file, or script file denies execution permission.

Create access on the extended swap file on a disk under Safeguard protection is denied.

This error occurs only for G-series TNS or accelerated new process image files.

The new process image file is not a regular file.

527186-003 Hewlett-Packard Company 8

69

tdm_spawnp(2) OSS System Calls Reference Manual

[EAGAIN]

[EBADF]

[EFAULT]

System resources such as disk space, process control block (PCB) space, MAP-

POOL space, stack space, or PFS space are temporarily inadequate.

A file descriptor pointed to by the fd_map[ ] parameter is invalid.

An address for a parameter in the process_extension structure pointed to by

pe_parms is out of allowable bounds. The Guardian PROCESS_LAUNCH_ error and error detail information is returned in the structure pointed to by the

pr_results parameter, unless pr_results contains a null pointer.

[EHLDSEM] The process tried to create a child process in a different processor while having at least one semadj value.

[EINVAL] One of these conditions exists:

An invalid parameter value was supplied in the process_extension structure pointed to by pe_parms. The Guardian PROCESS_LAUNCH_ error and error detail information is returned in the structure pointed to by the pr_results parameter, unless pr_results contains a null pointer.

The new process image file is a binary executable file with invalid attributes.

[EIO]

[ELOOP]

[EMFILE]

Some physical input or output error has occurred. Either a file cannot be opened because of an input or output error or data has been lost during an input or output transfer. This value is used only for errors on the object file of a loaded program or library, or during data transfer with a Guardian environment home terminal.

Too many symbolic links were encountered in pathname resolution.

The maximum number of files are open. The process attempted to open more than the maximum number of file descriptors allowed for the process. One of these conditions might exist:

The maximum value for fd_count has been exceeded.

The process file segment (PFS) of the child process is smaller than that of the parent process.

[ENAMETOOLONG]

One of these is too long:

The pathname pointed to by the file parameter

A component of the pathname pointed to by the file parameter

The intermediate result of pathname resolution when a symbolic link is part of the value specified by the file parameter

The pathconf( ) function can be called to obtain the applicable limits.

[ENOCPU] The selected processor does not exist, or the selected processor is down or otherwise unavailable for process creation.

[ENODEV] The system cannot find the fileset containing the process image file.

8

70 Hewlett-Packard Company 527186-003

System Functions (t) tdm_spawnp(2)

[ENOENT] One of these conditions exists:

One or more components of the new process image file’s pathname do not exist.

The file parameter points to an empty string.

[ENOEXEC] The command interpreter could not be invoked following failure to execute the process image file identified by the file parameter.

[ENOMEM] Required resources are not available. Subsequent calls to the same function will not succeed for the same reason.

Possible causes of this error include insufficient primary memory (stack, globals, or heap) for the new process.

[ENOTDIR] A component of the path prefix of the new process image file is not a directory.

[ENOTOSS] The calling process is not an OSS process. The tdm_spawnp( ) function cannot be used from the Guardian environment.

[EPERM] The value of the inherit->pgroup field does not match any process group ID in the same session as the calling process.

[ETXTBSY] The new process image file is a pure procedure (shared text) file that is currently open for writing by some process.

[EUNKNOWN]

Unknown error. An unrecognized or very obscure error occurred. If this error occurs, follow site-defined procedures for reporting software problems to

HP.

The structure pointed to by the pr_results parameter might contain additional Guardian

PROCESS_LAUNCH_ procedure error and error detail information if any of these errors occur:

[EACCES], [EAGAIN], [EFAULT], [EINVAL], [EIO], [ENOCPU], and [ENOEXEC].

RELATED INFORMATION

Commands: eld(1), ld(1), nld(1).

Functions: alarm(3), chmod(2), exec(2), _exit(2), exit(3), fcntl(2), fork(2), getenv(3),

putenv(3), semget(2), shmat(2), sigaction(2), system(3), tdm_execve(2), tdm_execvep(2),

tdm_fork(2), tdm_spawn(2), times(3), ulimit(2), umask(2).

Files: signal(4).

Miscellaneous: environ(5), process_extension_results(5).

STANDARDS CONFORMANCE

This function is an extension to the XPG4 Version 2 specification.

527186-003 Hewlett-Packard Company 8

71

Section 9. System Functions (u)

This section contains reference pages for Open System Services (OSS) system function calls with names that begin with u. These reference pages reside in the cat2 directory and are sorted alphabetically by U.S. English conventions in this section.

527186-003 Hewlett-Packard Company 9

1

ulimit(2) OSS System Calls Reference Manual

NAME

ulimit - Sets and gets file size limits

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <ulimit.h> long int ulimit(

int cmd [ ,

. . .

/*

*/

long int blk_size

] );

In this instance, the ellipsis ( . . . ) indicates that the function is variable. An additional, optional parameter can be specified.

PARAMETERS

cmd

Specifies the operation to be performed. The following values are valid:

blk_size

UL_GETFSIZE

Returns the size limit, in 512-byte blocks, of files opened by the process for writing in the OSS environment. (Files of any size can be read in the OSS environment.)

UL_SETFSIZE

Sets the size limit, in 512-byte blocks, of files opened by the process for writing in the OSS environment to the value specified as the second parameter of the call. (Files of any size can be read in the OSS environment.)

This is a restricted operation. Any process can reduce the size limit for its files, but only a process with appropriate privileges can increase the size limit for its files.

Specifies the number of 512-byte blocks to be permitted in a file written by the process. This parameter is required when the cmd parameter has the value of

UL_SETFSIZE. This parameter can be omitted in all other calls.

This parameter must be declared as a long int data type.

DESCRIPTION

The ulimit( ) function provides control over selected process limits. Limits set by calls to the

ulimit( ) function are inherited by a child process. Limits set by calls to the ulimit( ) function are enforced only if the file open was created by the OSS open( ) or creat( ) function call.

RETURN VALUES

Upon successful completion, the ulimit( ) function returns the value of the requested limit. If

ulimit( ) fails, the value -1 is returned, and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the ulimit( ) function sets errno to the value that corresponds to the condition.

[EINVAL] One of the following conditions exists:

9

2 Hewlett-Packard Company 527186-003

System Functions (u) ulimit(2)

[EPERM]

The value specified for the cmd parameter is not valid.

The value specified for the second parameter is too large.

The process does not have the appropriate privileges to perform the requested operation.

RELATED INFORMATION

Functions: creat(2), open(2), write(2).

STANDARDS CONFORMANCE

The following are HP extensions to the XPG4 Version 2 specification:

The error [EINVAL] is returned when the second parameter is too large.

527186-003 Hewlett-Packard Company 9

3

umask(2) OSS System Calls Reference Manual

NAME

umask - Sets and gets the value of the file mode creation mask

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/types.h>

/* optional except for POSIX.1 */

#include <sys/stat.h> mode_t umask(

mode_t cmask);

PARAMETERS

cmask

Specifies the value of the file mode creation mask.

DESCRIPTION

The umask( ) function sets the file mode creation mask of the process to the value of the cmask parameter and returns the previous value of the mask. The cmask parameter is constructed by logically ORing file permission bits defined in the sys/stat.h header file.

Whenever a file is created (by the creat( ), mkdir( ), mkfifo( ), mknod( ), or open( ) function), all file permission bits set in the file mode creation mask are cleared in the mode of the created file.

This clearing allows users to restrict the default access to their files.

The mask is inherited by child processes.

Use on Guardian Objects

The file mode creation mask of the process is not used when accessing a file in /G (the Guardian file system). If an open causes file creation, the file is given access permissions compatible with the standard security permissions for the Guardian creator access ID (CAID) of the calling process.

During access to a Guardian file, all Guardian environment access permissions are checked. This includes checks by Guardian standard security mechanisms and by the Safeguard product for

Guardian disk file and process access.

RETURN VALUES

Upon successful completion, the previous value of the file mode creation mask is returned.

RELATED INFORMATION

Commands: chmod(1), mkdir(1), sh(1), umask(1).

Functions: chmod(2), mkdir(2), mkfifo(3), mknod(2), open(2), stat(2).

9

4 Hewlett-Packard Company 527186-003

System Functions (u) uname(2)

NAME

uname - Gets information identifying the current system

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/utsname.h> int uname(

struct utsname *name);

PARAMETERS

name

Points to the utsname structure, where information about the current system is stored.

DESCRIPTION

The uname( ) function stores information identifying the current system in the structure pointed to by the name parameter.

The uname( ) function uses the utsname structure, which is defined in the sys/utsname.h file as follows:

struct utsname { char sysname [32]; char nodename[32]; char release [8]; char version [8]; char machine [16];

};

The uname( ) function returns null-terminated character strings describing the current system.

The sysname[ ] array indicates the operating system. For example, the HP implementation uses | the value "NONSTOP_KERNEL" on G-series release version updates (RVUs) through at least |

G06.25.

The nodename[ ] array contains the name that the system is known by on an Expand communications network; for example, "boston".

The release[ ] array identifies the release version (RV); for example, "H06" might appear for an |

H-series release version update.

The version[ ] array contains the version update number of the RVU. For example, "25" appears | for the G06.25 RVU.

The machine[ ] array indicates the processor hardware type being used; for example, "NSR-N" | or "NSR-T" might be used for a NonStop S-series server, while "NSE-A" might be used for a |

NonStop Integrity NS-series server.

Because the format and content of the utsname structure can change from release to release, it is not advisable to make programmatic choices based on the layout of the fields in this structure.

527186-003 Hewlett-Packard Company 9

5

uname(2) OSS System Calls Reference Manual

RETURN VALUES

Upon successful completion, a nonnegative value is returned. If the function call is unsuccessful, one of the following might happen:

The value -1 is returned and errno is set to indicate the error.

A Guardian trap is set.

ERRORS

If the following condition occurs, the uname( ) function sets errno to the corresponding value:

[EFAULT] The name parameter points outside of the process address space.

RELATED INFORMATION

Commands: uname(1).

STANDARDS CONFORMANCE

The following are HP extensions to the XPG4 Version 2 specification:

The error [EFAULT] can be returned.

9

6 Hewlett-Packard Company 527186-003

System Functions (u) unlink(2)

NAME

unlink - Removes a directory entry from the OSS environment

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <unistd.h> int unlink(

const char *path);

PARAMETERS

path

Specifies the directory entry to be removed.

DESCRIPTION

The unlink( ) function removes the directory entry specified by the path parameter and decrements the link count of the file referenced by the link.

When all links to a file are removed and no process has the file open, all resources associated with the file are reclaimed and the file is no longer accessible. If one or more processes have the file open when the last link is removed, the link is removed before the unlink( ) function returns but the removal of the file contents is postponed until all open references to the file are removed.

If the path parameter names a symbolic link, the symbolic link itself is removed.

The path parameter must not name a directory.

The calling process requires both execute (search) and write access permission for the directory containing the file being unlinked. Write permission for an OSS file is not required.

Upon successful completion, the unlink( ) function marks for update the st_ctime and st_mtime fields of the directory that contained the entry that was removed. If the file’s link count is not 0

(zero) or if the file is open, the st_ctime field of the file is also marked for update.

Use From the Guardian Environment

The unlink( ) function belongs to a set of functions that have the following effects when the first of them is called from the Guardian environment:

Two Guardian file system file numbers (not necessarily the next two available) are allocated for the root directory and the current working directory. These file numbers cannot be closed by calling the Guardian FILE_CLOSE_ procedure.

The current working directory is assigned from the VOLUME attribute of the Guardian environment =_DEFAULTS DEFINE.

The use of static memory by the process increases slightly.

These effects occur only when the first of the set of functions is called. The effects are not cumulative.

RETURN VALUES

Upon successful completion, the value 0 (zero) is returned. Otherwise, the value -1 is returned, the named file is not changed, and errno is set to indicate the error.

527186-003 Hewlett-Packard Company 9

7

unlink(2) OSS System Calls Reference Manual

ERRORS

If any of the following conditions occurs, the function sets errno to the corresponding value and the named file is not unlinked:

[EACCES]

[EBUSY]

One of the following conditions is true:

Search permission is denied for a component of the pathname prefix, or write permission is denied on the directory containing the link to be removed.

The S_ISVTX flag is set on the directory containing the existing file referred to by the path parameter. However, the calling process is not any of the following:

— The file owner

— The directory owner

— A process with appropriate privileges

The named file is one of the following:

The /dev/tty file

The /dev/null file

[EFAULT]

[EFSBAD]

The path parameter is an invalid address.

The fileset catalog for one of the filesets involved in the operation is corrupt.

[EGUARDIANOPEN]

One of the following conditions exists:

The named file is a Guardian file open in the Guardian environment.

The named file is a Guardian EDIT file (file code 101), and it is open in the OSS environment.

[EINVAL] The named file is a structured file in /G (the Guardian file system). Such files cannot be removed by the unlink( ) function.

[EIO] An input or output error occurred. The device holding the file might be in the down state, or both processors that provide access to the device might have failed.

Too many symbolic links were encountered in translating path.

[ELOOP]

[ENAMETOOLONG]

One of the following is too long:

The pathname pointed to by the path parameter

A component of the pathname pointed to by the path parameter

The intermediate result of pathname resolution when a symbolic link is part of the path parameter

The pathconf( ) function can be called to obtain the applicable limits.

9

8 Hewlett-Packard Company 527186-003

System Functions (u) unlink(2)

[ENOENT] One of the following conditions exists:

The named file does not exist.

The path parameter points to an empty string.

The path parameter specifies a file on a remote HP NonStop node but communication with the remote node has been lost.

[ENOROOT] One of the following conditions exists:

The root fileset of the local node (fileset 0) is not in the STARTED state.

The current root fileset for the specified file is unavailable. The OSS name server for the fileset might have failed.

The specified file is on a remote HP NonStop node and communication with the remote name server has been lost.

[ENOTDIR] A component of the pathname prefix is not a directory.

[ENXIO] The fileset containing the client’s current working directory or root directory is not mounted.

[EOSSNOTRUNNING]

The OSS monitor process is not running.

[EPERM] One of the following conditions exists:

The named file is a directory.

The named file is a Guardian file (in /G), but it is not a regular file.

[EROFS] The entry to be unlinked is part of a read-only fileset.

[ETXTBSY] One of the following conditions exists:

The entry to be unlinked is the last directory entry to a file that is already busy.

The named file is a NonStop SQL/MP object file that is currently executing.

RELATED INFORMATION

Commands: rm(1).

Functions: close(2), link(2), open(2), rmdir(2).

STANDARDS CONFORMANCE

The POSIX standards leave some features to the implementing vendor to define. The following features are affected in the HP implementation:

The calling process requires both execute (search) and write access permission for the directory containing the file being unlinked.

The unlink( ) function is not supported for directories.

527186-003 Hewlett-Packard Company 9

9

unlink(2) OSS System Calls Reference Manual

The following are HP extensions to the XPG4 Version 2 specification:

The errno values [EFAULT], [EFSBAD], [EGUARDIANOPEN], [EINVAL],

[ENOROOT], [ENXIO], and [EOSSNOTRUNNING] can be returned.

9

10 Hewlett-Packard Company 527186-003

System Functions (u) utime(2)

NAME

utime - Sets file access and modification times

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/types.h>

/* optional except for POSIX.1 */

#include <utime.h> int utime(

const char *path,

struct utimbuf *times);

PARAMETERS

path

Points to the pathname for the file. If the final component of the path parameter names a symbolic link, the link is traversed and pathname resolution continues.

Points to a utimbuf structure containing time values for the file.

times

DESCRIPTION

The utime( ) function sets the access and modification times of the file pointed to by the path parameter to the value of the times parameter. It allows time specifications that are accurate to the nearest second.

The times parameter is a pointer to a utimbuf structure, which is defined in the utime.h header file. The actime field in this structure represents the date and time of last access, and the mod-

time field represents the date and time of last modification. The times in the utimbuf structure are measured in seconds since the Epoch, which is 00:00:00, January 1, 1970, Coordinated

Universal Time (UTC).

If the times parameter is a null pointer, the access and modification times of the file are set to the current time. The effective user ID of the process either must be the same as the owner of the file, must have write access to the file, or must have appropriate privileges in order to use the call in this manner.

If the times parameter is not a null pointer, the access and modification times are set to the values contained in the designated structure. Only the owner of the file or a process with appropriate privileges can use the call this way.

Upon successful completion, the utime( ) function marks the time of the last file status change,

st_ctime, for update.

Use on Guardian Objects

The utime( ) function is supported for Guardian files (that is, files within /G) that are unstructured

Enscribe files. If the utime( ) function is called for a Guardian file that has a small file label, the label is expanded to include the st_atime and st_ctime fields and to mark them for update.

The utime( ) function cannot be used on a file in /G that is opened for execution. A call for such a file fails and errno is set to [ETXTBSY].

527186-003 Hewlett-Packard Company 9

11

utime(2) OSS System Calls Reference Manual

Use From the Guardian Environment

The file access time is not updated by I/O operations that are performed on a file that was opened in the Guardian environment (that is, by the FILE_OPEN_ or OPEN Guardian procedures).

The utime( ) function is one of a set of functions that have the following effects when the first of them is called from the Guardian environment:

Two Guardian file system file numbers (not necessarily the next two available) are allocated for the root directory and the current working directory. These file numbers cannot be closed by calling the Guardian FILE_CLOSE_ procedure.

The current working directory is assigned from the VOLUME attribute of the Guardian environment =_DEFAULTS DEFINE.

The use of static memory by the process increases slightly.

These effects occur only when the first of the set of functions is called. The effects are not cumulative.

RETURN VALUES

Upon successful completion, the value 0 (zero) is returned. Otherwise, the value -1 is returned,

errno is set to indicate the error, and the file times are not changed.

ERRORS

If any of the following conditions occurs, the utime( ) function sets errno to the corresponding value:

[EACCES] One of the following conditions exists:

Search permission is denied by a component of the pathname prefix.

The times parameter is a null pointer, the effective user ID neither is the owner of the file nor has appropriate privileges, and write access is denied.

[EFAULT]

[EFSBAD]

[EINVAL]

Either the path parameter or the times parameter is an invalid address.

The fileset catalog is corrupted for the fileset involved in the requested operation.

The function was called for a file in /G that is not a regular disk file.

[EIO] An input or output error occurred. The device holding the file might be in the down state, or both processors that provide access to the device might have failed.

Too many symbolic links were encountered in translating path.

[ELOOP]

[ENAMETOOLONG]

One of the following is too long:

The pathname pointed to by the path parameter

A component of the pathname pointed to by the path parameter

The intermediate result of pathname resolution when a symbolic link is part of the path parameter

The pathconf( ) function can be called to obtain the applicable limits.

9

12 Hewlett-Packard Company 527186-003

System Functions (u) utime(2)

[ENOENT] One of the following conditions exists:

The named file does not exist.

The path parameter points to an empty string.

The path parameter specifies a file on a remote HP NonStop node but communication with the remote node has been lost.

[ENOROOT] One of the following conditions exists:

The root fileset of the local node (fileset 0) is not in the STARTED state.

The current root fileset for the specified file is unavailable. The OSS name server for the fileset might have failed.

The specified file is on a remote HP NonStop node and communication with the remote name server has been lost.

[ENOTDIR] A component of the pathname prefix is not a directory.

[ENXIO] A request was made of a nonexistent device, or the request was outside the capabilities of the device.

[EOSSNOTRUNNING]

The OSS monitor process is not running.

[EPERM] The times parameter is not a null pointer, and the calling process has write access to the file but neither owns the file nor has appropriate privileges.

[EROFS] The fileset that contains the file is mounted read-only.

[ETXTBSY] The path parameter specifies a file in the Guardian file system (/G) that is opened for execution.

RELATED INFORMATION

Functions: stat(2).

STANDARDS CONFORMANCE

The following are HP extensions to the XPG4 Version 2 specification:

The errno values [EFAULT], [EFSBAD], [EINVAL], [ENOROOT], [ENXIO],

[EOSSNOTRUNNING], and [ETXTBSY] can be returned.

527186-003 Hewlett-Packard Company 9

13

Section 10. System Functions (w)

This section contains reference pages for Open System Services (OSS) system function calls with names that begin with w. These reference pages reside in the cat2 directory and are sorted alphabetically by U.S. English conventions in this section.

527186-003 Hewlett-Packard Company 10

1

wait(2) OSS System Calls Reference Manual

NAME

wait - Waits for any child process to terminate

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/types.h>

/* optional except for POSIX.1 */

#include <sys/wait.h> pid_t wait( int

∗∗

status_location);

PARAMETERS

status_location Points to a location that receives the child process termination status, as defined in the sys/wait.h header file.

DESCRIPTION

The wait( ) function usually suspends the calling process until one of the following occurs:

A child process initiates its own normal termination. That is, a child process calls the

_exit( ) or exit( ) function or the Guardian STOP or PROCESS_STOP_ procedure on itself.

A child process receives a signal that terminates the process. For example, some other process terminates the child process by calling the kill( ) function or the Guardian STOP or PROCESS_STOP_ procedure against the child process.

A child process terminates abnormally. The calling process receives a SIGABEND signal indicating that this process or another process has called the Guardian ABEND or

PROCESS_STOP_ procedure specifying abnormal termination of the child process, or the child process has abnormally terminated for some other reason.

The parent process catches a signal and invokes its own signal-catching function.

See the Guardian Procedure Calls Reference Manual for details on the Guardian ABEND,

STOP, and PROCESS_STOP_ procedures.

The wait( ) function returns without waiting if a child process that has not been waited for has already terminated prior to the call.

The effect of the wait( ) function can be modified by the setting of the SIGCHLD signal. See the

sigaction(2) reference page for details.

Use With POSIX Threads

If Release Version Update (RVU) G06.21, or later, of T1248 POSIX threads is installed on the system, the T1248 version of wait( ) is functionally equivalent to OSS wait( ), with the additional attribute of thread awareness. As such, it blocks only the thread calling it, without blocking any other threads. To call the T1248 wait( ) function, include the linking flag -l spt when compiling thread-aware applications. If more than one thread is waiting on child processes, use the

spt_waitpid( ) function.

Use From the Guardian Environment

If called from a Guardian process, the actions of this function are undefined and errno is set to

[ENOTOSS].

10

2 Hewlett-Packard Company 527186-003

System Functions (w) wait(2)

Status Information

If the wait( ) function returns because the status of a child process is available, it returns the OSS process ID of the child process. In this case, if the status_location parameter is not a null pointer, information is stored in the location pointed to by status_location.

The value stored at the location pointed to by status_location is 0 (zero) if and only if the status returned is from a terminated child process that either returned 0 (zero) from the main( ) function or passed 0 (zero) as the status parameter to the _exit( ) or exit( ) function.

Regardless of its value, this status information can be interpreted using the following macros, which are defined in the sys/wait.h header file and evaluate to integer expressions:

WCOMPLETION(

∗∗

status_location)

Evaluates to the 16-bit Guardian completion code issued on process termination.

WEXITSTATUS(

∗∗

status_location)

If the value of WIFEXITED(

∗∗

status_location) is nonzero, evaluates to one of the following:

The lower 8 bits of the status parameter that the child process passed to the _exit( ) or exit( ) function

The lower 8 bits of the completion code for a process that terminated itself by calling the Guardian STOP or PROCESS_STOP_ procedure

The lower 8 bits of the value that the child process returned from the

main( ) function

WIFABENDED(

∗∗

status_location)

Evaluates to a nonzero value if the child process terminated abnormally. A

SIGABEND signal was received.

WIFEXITED(

∗∗

status_location)

Evaluates to a nonzero value if status was returned for a child process that terminated normally whether the termination was due to the _exit( ) function, the

exit( ) function, the Guardian STOP procedure, or the Guardian

PROCESS_STOP_ procedure.

WIFSAVEABEND(

∗∗

status_location)

Evaluates to a nonzero value if the terminated process created a saveabend file.

WIFSIGNALED(

∗∗

status_location)

Evaluates to a nonzero value if status was returned for a child process that terminated due to the receipt of a signal that was not caught. Such a signal occurs, for example, when another process terminates the child process by calling the

kill( ) function, the Guardian STOP procedure, or the Guardian

PROCESS_STOP_ procedure, or when the process abnormally terminates.

WIFSTOPPED(

∗∗

status_location)

Evaluates to a nonzero value if status was returned for a child process that is currently stopped.

This macro is normally only useful with the waitpid( ) function.

527186-003 Hewlett-Packard Company 10

3

wait(2) OSS System Calls Reference Manual

WSTOPSIG(

∗∗

status_location)

If the value of WIFSTOPPED(

∗∗

status_location) is nonzero, evaluates to the number of the signal that caused the child process to stop.

This macro is normally only useful with the waitpid( ) function.

WTERMSIG(

∗∗

status_location)

If the value of WIFSIGNALED(

∗∗

status_location) is nonzero, evaluates to the number of the signal that caused the termination of the child process.

See the Guardian Procedure Calls Reference Manual for details on the Guardian STOP and

PROCESS_STOP_ procedures and on Guardian completion codes.

If the information stored at the location pointed to by the status_location parameter was stored there by a call to the waitpid( ) function that specified the WUNTRACED option, exactly one of the WIFEXITED, WIFSIGNALED, and WIFSTOPPED macros evaluates to a nonzero value.

If the information stored at the location pointed to by status_location was stored there by a call to the wait( ) function, exactly one of the WIFEXITED and WIFSIGNALED macros evaluates to a nonzero value.

Normal Self Termination

When a process terminates itself, information is returned to the parent process in the location pointed to by the status_location parameter. A process terminates itself in one of the following ways:

Returning from its main( ) function. The return value is placed in

∗∗

status_location.

Calling the _exit( ) or exit( ) function. The exit status is placed in

∗∗

status_location.

Calling the Guardian STOP or PROCESS_STOP_ procedure with parameters set for self-termination. The completion code is placed in

∗∗

status_location.

The parent process can use the WIFEXITED macro to detect a child process that terminates itself; WIFEXITED evaluates to a nonzero value. The WEXITSTATUS macro evaluates to the lower 8 bits of the return value, exit status, or completion code. The WCOMPLETION macro evaluates to the full 16-bit completion code or to 16 bits of the 32-bit exit status code.

See the Guardian Procedure Calls Reference Manual for details on the Guardian STOP and

PROCESS_STOP_ procedures and on Guardian completion codes.

Termination by Another

The child process can be terminated by another process in one of the following ways:

Another process calls the kill( ) function with the OSS process ID of the child process.

Another process calls the Guardian STOP procedure with the Guardian process ID of the child process or calls the Guardian PROCESS_STOP_ procedure with the Guardian process handle of the child process.

In either case, the SIGKILL signal is delivered. The parent process can use the WIFSIG-

NALED macro to detect when a signal causes the child process to terminate; WIFSIGNALED evaluates to a nonzero value. The WTERMSIG macro evaluates to the number of the signal that caused the termination. The WCOMPLETION macro evaluates to the completion code.

See the Guardian Procedure Calls Reference Manual for details on the Guardian STOP and

PROCESS_STOP_ procedures and on Guardian completion codes.

10

4 Hewlett-Packard Company 527186-003

System Functions (w) wait(2)

Abnormal Termination

Abnormal termination can occur for several reasons, including the following:

The child process calls the Guardian ABEND procedure, or it calls the Guardian

PROCESS_STOP_ procedure with the parameters set for abnormal termination.

The processor in which the process was running fails.

Some critical system resource is exhausted.

One of the functions in the exec, tdm_exec, or tdm_spawn set of functions fails after the caller of that function has already been overlaid by the child process, and there is no caller to which it can return the error.

Two traps occur inside an area where a Guardian trap handler is installed by the Guardian SETTRAP procedure.

In all cases of abnormal termination, the SIGABEND signal is delivered. Like the SIGKILL signal, SIGABEND can neither be caught nor ignored. Its default action is to terminate the process.

The WIFSIGNALED macro evaluates to a nonzero value and the SIGABEND signal is indicated by the WTERMSIG macro. Alternatively, the parent process can use the WIFABENDED macro to determine whether the child process terminated abnormally. The parent process can use the WCOMPLETION macro to read the completion code.

See the Guardian Procedure Calls Reference Manual for details on the Guardian ABEND,

STOP, and PROCESS_STOP_ procedures and on Guardian completion codes.

Saveabend File Creation

Whenever process termination is caused by signal delivery (that is, when the WIFSIGNALED macro evaluates to a nonzero value), it is possible that the terminating process creates a saveabend file.

A saveabend file is created for the process if the saveabend bit is set for the process in the process control block (PCB). This bit is set in any of the following ways:

The compiler, linker, or Binder sets the saveabend bit in the code file header.

The tdm_fork( ), tdm_execve( ), tdm_execvep( ), tdm_spawn( ), or tdm_spawnp( ) function sets the pe_debug_options field of the process_extensions_def structure.

The shell command that executes the process sets the saveabend bit.

If a saveabend file is created, the core dump (CD) bit is set in the information returned in the location pointed to by the status_location parameter. The parent process can use the

WIFSAVEABEND macro to detect the creation of a saveabend file;

WIFSAVEABEND evaluates to a nonzero value when the CD bit is set.

If a processor failure occurs, status about the terminated child processes in the failed processor is returned to the parent process in the location pointed to by the status_location parameter. In this case, no saveabend file is possible. WIFSAVEABEND evaluates to zero.

NOTES

If a parent process terminates without waiting for all of its child processes to terminate, the remaining child processes are assigned a parent process ID of 1.

Suspending a process is not always the same as stopping it. A process is only stopped when a job-control signal stops it.

527186-003 Hewlett-Packard Company 10

5

wait(2) OSS System Calls Reference Manual

RETURN VALUES

If the wait( ) function returns because the status of a child process is available, the OSS process

ID of the child is returned to the calling process. If a signal is received via pthread_kill(2) that is not blocked,ignored, or handled, -1 is returned with an errno of EINTR.

Upon any error, the value -1 is returned and errno is set to indicate the error.

ERRORS

If any of the following conditions occurs, the wait( ) function sets errno to the corresponding value:

[ECHILD]

[EFAULT]

[EINTR]

The calling process has no existing unwaited-for child processes.

The buffer pointed to by the status_location parameter failed bounds checking.

The function was terminated by receipt of a signal. The information pointed to by the status_location parameter is not meaningful when this error occurs and should not be used in further processing.

[ENOTOSS] The calling process was not an OSS process. The wait( ) function cannot be used in the Guardian environment.

RELATED INFORMATION

Functions: exec(2), _exit(2), exit(3), fork(2), spt_waitpid(2), pause(3), sigaction(2),

tdm_execve(2), tdm_execvep(2), tdm_fork(2), tdm_spawn(2), tdm_spawnp(2), waitpid(2).

STANDARDS CONFORMANCE

The POSIX standards leave some features to the implementing vendor to define. The following features are affected in the HP implementation:

The POSIX.1 standard states that when status information for two or more child processes is available, the order in which the information is returned by the wait( ) function is unspecified. HP’s implementation also does not provide this information in a specified sequence. The sequence should therefore not be depended upon for further processing.

In addition to the status information mandated by the POSIX.1 standard, the HP implementation also returns status information for processes that terminate as a result of Guardian procedure calls. In addition, status is returned for processes that terminate abnormally as a result of a situation that is unique to NonStop server architecture, such as failure of the child process’s processor while the parent process continues to execute.

The POSIX.1 standard indicates that the value in the location pointed to by the

status_location parameter is undefined when errno returns the value [EINTR]. HP’s implementation also does not return meaningful information, and the value should not be used for further processing.

10

6 Hewlett-Packard Company 527186-003

System Functions (w) waitpid(2)

NAME

waitpid - Waits for a specific child process to stop or terminate

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/types.h>

/* optional except for POSIX.1 */

#include <sys/wait.h> pid_t waitpid(

pid_t process_id,

int

∗∗

status_location,

int options);

PARAMETERS

process_id

Specifies the child process.

status_location Points to a location that receives the child process termination (or stop) status, as defined in the sys/wait.h header file.

options

Modifies the behavior of the function.

DESCRIPTION

The waitpid( ) function usually suspends the calling process until one of the following occurs:

The specified child process initiates its own normal termination. That is, the child process calls the _exit( ) or exit( ) function or the Guardian STOP or PROCESS_STOP_ procedure on itself.

The child process receives a signal that terminates the process. For example, some other process terminates the child process by calling the kill( ) function or the Guardian STOP or PROCESS_STOP_ procedure against the child process.

The child process terminates abnormally. The calling process receives a SIGABEND signal indicating that this process or another process has called the Guardian ABEND or

PROCESS_STOP_ procedure specifying abnormal termination of the child process, or the child process has abnormally terminated for some other reason.

The child process was stopped (that is, suspended) by a job-control signal and the WUN-

TRACED option was set in this call to waitpid( ).

The parent process catches a signal and invokes its own signal-catching function.

See the Guardian Procedure Calls Reference Manual for details on the Guardian ABEND,

STOP, and PROCESS_STOP_ procedures.

The waitpid( ) function returns without waiting if a child process that has not been waited for has already stopped or terminated prior to the call.

The POSIX.1 standard states that when status information for two or more child processes is available, the order in which the information is returned by the waitpid( ) function is unspecified.

HP’s implementation also does not provide this information in a reliable sequence. The sequence should therefore not be depended upon for further processing.

The effect of the waitpid( ) function can be modified by the setting of the SIGCHLD signal. See the sigaction(2) reference page for details.

The waitpid( ) function behaves identically to the wait( ) function if the process_id parameter has the value -1 and the options parameter has the value 0 (zero). Otherwise, its behavior is

527186-003 Hewlett-Packard Company 10

7

waitpid(2) OSS System Calls Reference Manual

modified by the values of the process_id and options parameters.

Use From the Guardian Environment

If called from a Guardian process, the actions of this function are undefined and errno is set to

[ENOTOSS].

Specifying the Child Process

The waitpid( ) function allows the calling process to gather status from a specific set of child processes. The waitpid( ) function returns the status of a child process from this set. The

process_id parameter specifies the set according to the following rules:

If process_id is equal to -1, status is requested for any child process. In this respect, the

waitpid( ) function is equivalent to the wait( ) function.

If process_id is greater than 0 (zero), it specifies the OSS process ID (PID) of a single child process for which status is requested.

If process_id is equal to 0 (zero), status is requested for any child process whose process group ID is equal to that of the calling process.

If process_id is less than -1, status is requested for any child process whose process group ID is equal to the absolute value of process_id.

Options

The options parameter modifies the behavior of the waitpid( ) function. This parameter is constructed from the bitwise-inclusive OR of the following flag values:

WNOHANG

Prevents the calling process from being suspended even if there are child processes to wait for. In this case, 0 (zero) is returned, indicating that there are no child processes that have stopped or terminated.

WUNTRACED

Returns information when child processes of the current process are stopped because they received a SIGTTIN, SIGTTOU, SIGSTOP, or SIGTSTP signal.

Status Information

If the waitpid( ) function returns because the status of a child process is available, it returns the

OSS process ID of the child process. In this case, if the status_location parameter is not a null pointer, information is stored in the location pointed to by status_location.

The value stored at the location pointed to by status_location is 0 (zero) if and only if the status returned is from a terminated child process that either returned 0 (zero) from the main( ) function or passed 0 (zero) as the status parameter to the _exit( ) or exit( ) function.

Regardless of its value, this status information can be interpreted using the following macros, which are defined in the sys/wait.h header file and evaluate to integer expressions:

WCOMPLETION(

∗∗

status_location)

Evaluates to the 16-bit Guardian completion code issued on process termination.

WEXITSTATUS(

∗∗

status_location)

If the value of WIFEXITED(

∗∗

status_location) is nonzero, evaluates to one of the following:

The lower 8 bits of the status parameter that the child process passed to the _exit( ) or exit( ) function

10

8 Hewlett-Packard Company 527186-003

System Functions (w) waitpid(2)

The lower 8 bits of the completion code for a process that terminated itself by calling the Guardian STOP or PROCESS_STOP_ procedure

The lower 8 bits of the value that the child process returned from the

main( ) function

WIFABENDED(

∗∗

status_location)

Evaluates to a nonzero value if the child process terminated abnormally. A

SIGABEND signal was received.

WIFEXITED(

∗∗

status_location)

Evaluates to a nonzero value if status was returned for a child process that terminated normally whether the termination was due to the _exit( ) function, the

exit( ) function, the Guardian STOP procedure, or the Guardian

PROCESS_STOP_ procedure.

WIFSAVEABEND(

∗∗

status_location)

Evaluates to a nonzero value if the terminated process created a saveabend file.

WIFSIGNALED(

∗∗

status_location)

Evaluates to a nonzero value if status was returned for a child process that terminated due to the receipt of a signal that was not caught. Such a signal occurs, for example, when another process terminates the child process by calling the

kill( ) function, the Guardian STOP procedure, or the Guardian

PROCESS_STOP_ procedure, or when the process abnormally terminates.

WIFSTOPPED(

∗∗

status_location)

Evaluates to a nonzero value if status was returned for a child process that is currently stopped.

This macro returns a nonzero value only when the WUNTRACED option was set in the call to waitpid( ) and the stopped process was not previously reported.

WSTOPSIG(

∗∗

status_location)

If the value of WIFSTOPPED(

∗∗

status_location) is nonzero, evaluates to the number of the signal that caused the child process to stop.

WTERMSIG(

∗∗

status_location)

If the value of WIFSIGNALED(

∗∗

status_location) is nonzero, evaluates to the number of the signal that caused the termination of the child process.

See the Guardian Procedure Calls Reference Manual for details on the Guardian STOP and

PROCESS_STOP_ procedures and on Guardian completion codes.

If the information stored at the location pointed to by the status_location parameter was stored there by a call to the waitpid( ) function that specified the WUNTRACED option, exactly one of the WIFEXITED, WIFSIGNALED, and WIFSTOPPED macros evaluates to a nonzero value.

If the information stored at the location pointed to by status_location was stored there by a call to

waitpid( ) that did not specify the WUNTRACED option or by a call to the wait( ) function, exactly one of the WIFEXITED and WIFSIGNALED macros evaluates to a nonzero value.

Normal Self Termination

When a process terminates itself, information is returned to the parent process in the location pointed to by the status_location parameter. A process terminates itself in one of the following ways:

Returning from its main( ) function. The return value is placed in

∗∗

status_location.

527186-003 Hewlett-Packard Company 10

9

waitpid(2) OSS System Calls Reference Manual

Calling the _exit( ) or exit( ) function. The exit status is placed in

∗∗

status_location.

Calling the Guardian STOP or PROCESS_STOP_ procedure with parameters set for self-termination. The completion code is placed in

∗∗

status_location.

The parent process can use the WIFEXITED macro to detect a child process that terminates itself; WIFEXITED evaluates to a nonzero value. The WEXITSTATUS macro evaluates to the lower 8 bits of the return value, exit status, or completion code. The WCOMPLETION macro evaluates to the full 16-bit completion code or to 16 bits of the 32-bit exit status code.

See the Guardian Procedure Calls Reference Manual for details on the Guardian STOP and

PROCESS_STOP_ procedures and on Guardian completion codes.

Termination by Another

The child process can be terminated by another process in one of the following ways:

Another process calls the kill( ) function with the OSS process ID of the child process.

Another process calls the Guardian STOP procedure with the Guardian process ID of the child process or calls the Guardian PROCESS_STOP_ procedure with the Guardian process handle of the child process.

In either case, the SIGKILL signal is delivered. The parent process can use the WIFSIG-

NALED macro to detect when a signal causes the child process to terminate; WIFSIGNALED evaluates to a nonzero value. The WTERMSIG macro evaluates to the number of the signal that caused the termination. The WCOMPLETION macro evaluates to the completion code.

See the Guardian Procedure Calls Reference Manual for details on the Guardian STOP and

PROCESS_STOP_ procedures and on Guardian completion codes.

Abnormal Termination

Abnormal termination can occur for several reasons, including the following:

The child process calls the Guardian ABEND procedure, or it calls the Guardian

PROCESS_STOP_ procedure with the parameters set for abnormal termination.

The processor in which the process was running fails.

Some critical system resource is exhausted.

One of the functions in the exec, tdm_exec, or tdm_spawn set of functions fails after the caller of that function has already been overlaid by the child process, and there is no caller to which it can return the error.

Two traps occur inside an area where a Guardian trap handler is installed by the Guardian SETTRAP procedure.

In all cases of abnormal termination, the SIGABEND signal is delivered. Like the SIGKILL signal, SIGABEND can neither be caught nor ignored. Its default action is to terminate the process.

The WIFSIGNALED macro evaluates to a nonzero value and the SIGABEND signal is indicated by the WTERMSIG macro. Alternatively, the parent process can use the WIFABENDED macro to determine whether the child process terminated abnormally. The parent process can use the WCOMPLETION macro to read the completion code.

See the Guardian Procedure Calls Reference Manual for details on the Guardian ABEND,

STOP, and PROCESS_STOP_ procedures and on Guardian completion codes.

10

10 Hewlett-Packard Company 527186-003

System Functions (w) waitpid(2)

Process Stopped

If the WUNTRACED option is set in the waitpid( ) call, the call returns when the child process is temporarily suspended because it received a SIGTTIN, SIGTTOU, SIGSTOP, or

SIGTSTOP signal.

The WIFSTOPPED macro evaluates to a nonzero value. The WSTOPSIG macro evaluates to the number of the signal that caused the process to stop.

Saveabend File Creation

Whenever process termination is caused by signal delivery (that is, when the WIFSIGNALED macro evaluates to a nonzero value), it is possible that the terminating process creates a saveabend file.

A saveabend file is created for the process if the saveabend bit is set for the process in the process control block (PCB). This bit is set in any of the following ways:

The compiler, linker, or Binder sets the saveabend bit in the code file header.

The tdm_fork( ), tdm_execve( ), tdm_execvep( ), tdm_spawn( ), or tdm_spawnp( ) function sets the pe_debug_options field of the process_extensions_def structure.

The shell command that executes the process sets the saveabend bit.

If a saveabend file is created, the core dump (CD) bit is set in the information returned in the location pointed to by the status_location parameter. The parent process can use the

WIFSAVEABEND macro to detect the creation of a saveabend file;

WIFSAVEABEND evaluates to a nonzero value when the CD bit is set.

If a processor failure occurs, status about the terminated child processes in the failed processor is returned to the parent process in the location pointed to by the status_location parameter. In this case, no saveabend file is possible. WIFSAVEABEND evaluates to zero.

NOTES

If a parent process terminates without waiting for all of its child processes to terminate, the remaining child processes are assigned a parent process ID of 1.

Suspending a process is not always the same as stopping it. A process is only stopped when a job-control signal stops it.

RETURN VALUES

If the waitpid( ) function returns because the status of a child process is available, the OSS process ID of the child is returned to the calling process. If the function returns because a signal was caught by the calling process, the value -1 is returned and errno is set to [EINTR]. Upon any error, the value -1 is returned and errno is set to indicate the error.

If the WNOHANG value of the options parameter was specified and there are no stopped or exited child processes, the waitpid( ) function returns the value 0 (zero).

ERRORS

If any of the following conditions occurs, the waitpid( ) function sets errno to the corresponding value:

[ECHILD]

[EFAULT]

The process or process group ID specified by the process_id parameter either does not exist or is not a child process of the calling process.

The buffer pointed to by the status_location parameter failed bounds checking.

527186-003 Hewlett-Packard Company 10

11

waitpid(2) OSS System Calls Reference Manual

[EINTR] The function was terminated by receipt of a signal. The information pointed to by the status_location parameter is not meaningful when this error occurs and should not be used in further processing.

[EINVAL] The value of the options parameter is invalid.

[ENOTOSS] The calling process was not an OSS process. The waitpid( ) function cannot be used in the Guardian environment.

RELATED INFORMATION

Functions: exec(2), _exit(2), exit(3), fork(2), pause(3), sigaction(2), tdm_execve(2),

tdm_execvep(2), tdm_fork(2), tdm_spawn(2), tdm_spawnp(2), wait(2).

STANDARDS CONFORMANCE

The POSIX standards leave some features to the implementing vendor to define. The following features are affected in the HP implementation:

The POSIX.1 standard states that when status information for two or more child processes is available, the order in which the information is returned by the waitpid( ) function is unspecified. HP’s implementation also does not provide this information in a specified sequence. The sequence should therefore not be depended upon for further processing.

In addition to the status information mandated by the POSIX.1 standard, the HP implementation also returns status information for processes that terminate as a result of Guardian procedure calls. In addition, status is returned for processes that terminate abnormally as a result of a situation that is unique to HP NonStop server architecture, such as failure of the child process’s processor while the parent process continues to execute.

The POSIX.1 standard indicates that the value in the location pointed to by the

status_location parameter is undefined when errno returns the value [EINTR]. HP’s implementation also does not return meaningful information, and the value should not be used for further processing.

10

12 Hewlett-Packard Company 527186-003

System Functions (w)

527186-003 Hewlett-Packard Company

write(2)

NAME

write - Writes to a file

LIBRARY

G-series native OSS processes: system library

H-series OSS processes: implicit libraries

SYNOPSIS

#include <sys/types.h>

/* optional except for POSIX.1 */

#include <unistd.h> ssize_t write(

int filedes,

void *buffer,

size_t nbytes);

PARAMETERS

filedes buffer nbytes

Specifies an open file descriptor obtained from a successful call to the accept( ),

creat( ), dup( ), dup2( ), fcntl( ), open( ), pipe( ), socket( ), or socketpair( ) function.

Identifies the buffer containing the data to be written.

Specifies the number of bytes to write.

DESCRIPTION

The write( ) function attempts to write nbytes of data to the file associated with the filedes parameter from the buffer pointed to by the buffer parameter.

For all regular and nonregular files, if the value of the nbytes parameter is 0 (zero) and the value of filedes is a valid file descriptor, the write( ) function returns 0 (zero).

The appropriate file time fields are updated unless nbytes is 0 (zero).

With regular files and devices capable of seeking, the actual writing of data proceeds from the position in the file indicated by the file pointer. If this incremented file pointer is greater than the length of the file, the length of the file is set to this file offset. Upon return from the write( ) function, the file pointer is incremented by the number of bytes actually written.

With devices incapable of seeking, writing always takes place starting at the current position.

For such devices, the value of the file pointer after a call to the write( ) function is always 0

(zero).

Fewer bytes than requested can be written if there is not enough room to satisfy the request. In this case, the number of bytes written is returned. For example, suppose there is space for 20 bytes more in a file before reaching a limit. A write request of 512 bytes returns a value of 20.

The limit reached can be either the end of the physical medium or the value that has been set by the ulimit( ) function. The next write of a nonzero number of bytes gives a failure return (except as noted later).

Upon successful completion, the write( ) function returns the number of bytes actually written to the file associated with filedes. This number is never greater than the value of nbytes.

If the O_APPEND flag of the file status is set, the file offset is set to the end of the file prior to each write.

If the O_SYNC flag of the file status is set and filedes refers to a regular file, a successful write( ) call does not return until the data is delivered to the underlying hardware (as described in the

open(2) reference page).

The O_NONBLOCK flag is effective only on pipes, FIFOs, and sockets.

10

13

write(2) OSS System Calls Reference Manual

Write requests to a pipe or a FIFO file are handled the same as writes to a regular file with these exceptions:

No file offset is associated with a pipe; therfore, each write( ) request appends to the end of the pipe.

If the size of the write( ) request is less than or equal to the value of the PIPE_BUF system variable, the write( ) function is guaranteed to be atomic. The data is not interleaved with data from other processes doing writes on the same pipe.

If the size of the write( ) request is greater than the value of the PIPE_BUF system variable, the file system attempts to resize the pipe buffer from 2 * PIPE_BUF to 65,536 bytes. If the resizing is successful, the file system performs atomic writes of up to 32,768 bytes and can transfer up to 52 kilobytes of data from the pipe buffer on subsequent

read( ) or readv( ) calls by the client.

If the file system cannot resize the buffer, it continues to use the existing buffer. A second attempt at resizing occurs after approximately a minute elapses.

Writes of greater than PIPE_BUF bytes can have data interleaved, on arbitrary boundaries, with writes by other processes, whether or not the O_NONBLOCK flag is set.

If the O_NONBLOCK flag is not set, a write( ) request to a full pipe causes the process to block until enough space becomes available to handle the entire request.

If the O_NONBLOCK flag is set, write( ) requests are handled differently in these ways:

— The write( ) function does block the process.

write( ) requests for PIPE_BUF or fewer bytes either succeed completely and return the value of the nbytes parameter, or return the value -1 and set errno to

[EAGAIN].

— A write( ) request for greater than PIPE_BUF bytes either transfers what it can and returns the number of bytes written, or transfers no data and returns the value

-1 with errno set to [EAGAIN]. Also, if a request is greater than PIPE_BUF bytes and all data previously written to the pipe has been read, write( ) transfers at least PIPE_BUF bytes.

When attempting to write to a socket and with no space available for data:

If the O_NONBLOCK flag is not set, the write( ) function blocks until space becomes available.

If the O_NONBLOCK flag is set, the write( ) function returns the value -1 and sets

errno to [EAGAIN]. The O_NONBLOCK flag has no effect if there is space available.

Upon successful completion, the write( ) function marks the st_ctime and st_mtime fields of the file for update and clears the set-user-ID and set-group-ID attributes if the file is a regular file.

The fcntl( ) function provides more information about record locks.

If it is interrupted by a signal before it writes any data, the write( ) function returns the value -1 with errno set to [EINTR]. If it is interrupted by a signal after it has successfully written some data, the write( ) function returns the number of bytes that it has written.

10

14 Hewlett-Packard Company 527186-003

System Functions (w) write(2)

Use on Guardian Objects

Attempting to write to a Guardian file (that is, a file in /G) that is locked causes the write( ) function to return -1 and set errno to [EGUARDIANLOCKED].

RETURN VALUES

Upon successful completion, the write( ) function returns the number of bytes that were actually written. Otherwise, the value -1 is returned, and errno is set to indicate the error.

ERRORS

If any of these conditions occurs, the write( ) function sets errno to the corresponding value:

[EAGAIN] One of these conditions exists:

An attempt was made to write to a file descriptor that cannot accept data, and the O_NONBLOCK flag is set.

A write to a pipe (FIFO file) of PIPE_BUF bytes or less is requested,

O_NONBLOCK is set, and fewer than nbytes of free space are available.

The O_NONBLOCK flag is set on this file, and the process would be delayed in the write operation.

[EBADF] The filedes parameter does not specify a valid file descriptor open for writing.

[ECONNRESET]

One of these conditions occurred:

The transport-provider process for this socket is no longer available.

The TCP/IP subsystem for this socket is no longer available.

The connection was forcibly closed by the peer socket.

The file descriptor specified by the filedes parameter can only be closed.

[EFAULT]

[EFBIG]

The buffer parameter points to a location outside of the allocated address space of the process.

An attempt was made to write a file that exceeds the maximum file size.

[EGUARDIANLOCKED]

A write( ) operation was attempted to a file in the Guardian file system (that is, a file in /G) that is locked.

[EINTR] A write( ) operation was interrupted by a signal before any data was written.

[EINVAL] One of these conditions occurred:

The file position pointer associated with the file specified by the filedes parameter was negative.

The value of the nbytes parameter is greater than SSIZE_MAX.

[EIO] One of these conditions occurred:

The process is a member of a background process group attempting to write to its controlling terminal, the TOSTOP flag is set, the process is neither ignoring nor blocking the SIGTTOU signal, and the process group of the process is orphaned.

527186-003 Hewlett-Packard Company 10

15

write(2) OSS System Calls Reference Manual

A physical I/O error occurred. Data might have been lost during a transfer.

[EISGUARDIAN]

The value used for the filedes parameter is appropriate only in the Guardian environment.

[ENETDOWN]

The filedes parameter specifies a file on a remote HP NonStop node, but communication with the remote node has been lost.

[ENOSPC] No free space is left on the fileset containing the file.

[ENOTCONN] An attempt was made to write to a socket that is not connected to a peer socket.

[ENXIO] One of these conditions occurred:

The device associated with the file descriptor specified by the filedes parameter is a block special device or character special file, and the file pointer is out of range.

No existing device is associated with the file descriptor specified by the

filedes parameter.

[EPIPE] One of these conditions occurred:

An attempt was made to write to a pipe or FIFO file that is not open for reading by any process. A SIGPIPE signal is sent if the process is running in the OSS environment.

An attempt was made to write to a pipe that has only one end open.

An attempt was made to write to a socket that is shut down or closed.

[ETIMEDOUT]

Data transmission on the socket timed out.

[EWRONGID] One of these conditions occurred:

The process attempted an operation through an operating system input/output process (such as a terminal server process) that has failed or is in the down state.

The processor for the disk process of the specified file failed during an input or output operation, and takeover by the backup process occurred.

The open file descriptor has migrated to a new processor, but the new processor lacks a resource or system process needed for using the file descriptor.

The file descriptor specified by the filedes parameter can only be closed.

For all other error conditions, errno is set to the appropriate Guardian file-system error number.

See the Guardian Procedure Errors and Messages Manual for more information about a specific

Guardian file-system error.

10

16 Hewlett-Packard Company 527186-003

System Functions (w) write(2)

RELATED INFORMATION

Functions: creat(2), fcntl(2), lseek(2), open(2), pipe(2), socket(2), ulimit(3).

STANDARDS CONFORMANCE

The HP implementation does not:

Return the errno value [EWOULDBLOCK] for a call on a socket that does not have

O_NONBLOCK set and does not have space available to receive data

Generate the SIGXFSZ signal

The POSIX standards leave some features to the implementing vendor to define. These features are affected in the HP implementation:

Calls to the write( ) function with the nbytes parameter equal to 0 are supported for all regular and nonregular files.

After reading from a device that is incapable of seeking, the value of the file pointer is always 0 (zero).

Specifying a value for the nbytes parameter that is greater than SSIZE_MAX causes the

write( ) function to return -1 and set errno to [EINVAL].

errno can be set to [EIO] if a physical I/O error occurs.

HP extensions to the XPG4 Version 2 specification are:

The errno values [ECONNRESET], [EFAULT], [EGUARDIANLOCKED], [EINVAL],

[ENETDOWN], [ENOTCONN], [ETIMEDOUT], and [EWRONGID] can be returned.

527186-003 Hewlett-Packard Company 10

17

writev(2) OSS System Calls Reference Manual

NAME

writev - Writes to a file from scattered buffers

LIBRARY

G-series native OSS processes: /G/system/sysnn/zossesrl

H-series OSS processes: /G/system/zdllnnn/zossedll

SYNOPSIS

#include <sys/types.h>

#include <sys/uio.h> int writev(

int filedes,

struct iovec *iov,

int iov_count);

PARAMETERS

filedes iov iov_count

Specifies an open file descriptor obtained from a successful call to the accept( ),

creat( ), dup( ), dup2( ), fcntl( ), open( ), pipe( ), socket( ), or socketpair( ) function.

Points to a iovec structure that identifies the buffers containing the data to be written.

Specifies the number of iovec structure entries (buffers) pointed to by the iov parameter.

DESCRIPTION

The writev( ) function attempts to write data to the file associated with the filedes parameter from the set of buffers pointed to by the iov parameter.

The writev( ) function performs the same action as the write( ) function, but gathers the output data from the iov_count buffers specified by the iovec structure buffers pointed to by the iov parameter.

The iovec structure is defined in the sys/uoi.h header file and contains entries with these members:

caddr_t iov_base; int iov_len;

The iov_base and iov_len members of each iovec structure entry specify the base address and length of an area in memory from which data should be written. The writev( ) function always writes a complete buffer before proceeding to the next.

With regular files and devices capable of seeking, the actual writing of data proceeds from the position in the file indicated by the file pointer. If this incremented file pointer is greater than the length of the file, the length of the file is set to this file offset. Upon return from the writev( ) function, the file pointer is incremented by the number of bytes actually written.

With devices incapable of seeking, writing always takes place starting at the current position.

For such devices, the value of the file pointer after a call to the writev( ) function is always 0

(zero).

Fewer bytes than requested can be written if there is not enough room to satisfy the request. In this case, the number of bytes written is returned. For example, suppose there is space for 20 bytes more in a file before reaching a limit. A write request of 512 bytes returns a value of 20.

The limit reached can be either the end of the physical medium or the value that has been set by the ulimit( ) function. The next write of a nonzero number of bytes gives a failure return (except as noted later).

10

18 Hewlett-Packard Company 527186-003

System Functions (w) writev(2)

Upon successful completion, the writev( ) function returns the number of bytes actually written to the file associated with filedes.

If the O_APPEND status flag of the file is set, the file offset is set to the end of the file prior to each write.

If the O_SYNC status flag of the file is set and filedes refers to a regular file, a successful wri-

tev( ) call does not return until the data is delivered to the underlying hardware (as described in the open(2) reference page).

The O_NONBLOCK flag is effective only on pipes, FIFOs, sockets, and terminal device files

(Telserv or OSSTTY processes).

Write requests to a pipe or FIFO file are handled the same as writes to a regular file with these exceptions:

No file offset is associated with a pipe; therfore, each writev( ) request appends to the end of the pipe.

If the size of the writev( ) request is less than or equal to the value of the PIPE_BUF system variable, the writev( ) function is guaranteed to be atomic. The data is not interleaved with data from other processes doing writes on the same pipe.

If the size of the writev( ) request is greater than the value of the PIPE_BUF system variable, the file system attempts to resize the pipe buffer from 2 * PIPE_BUF to 65,536 bytes. If the resizing is successful, the file system performs atomic writes of up to 32,768 bytes and can transfer up to 52 kilobytes of data from the pipe buffer on subsequent

read( ) or readv( ) calls by the client.

If the file system cannot resize the buffer, it continues to use the existing buffer. A second attempt at resizing occurs after approximately a minute elapses.

Writes of greater than PIPE_BUF bytes can have data interleaved, on arbitrary boundaries, with writes by other processes, whether or not the O_NONBLOCK flag is set.

If the O_NONBLOCK flag is not set, a writev( ) request to a full pipe causes the process to block until enough space becomes available to handle the entire request.

If the O_NONBLOCK flag is set, writev( ) requests are handled differently in these ways:

— The writev( ) function does block the process.

writev( ) requests for PIPE_BUF or fewer bytes either succeed completely and return the number of bytes written, or return the value -1 and set errno to

[EAGAIN].

— A writev( ) request for greater than PIPE_BUF bytes either transfers what it can and returns the number of bytes written, or transfers no data and returns the value

-1 with errno set to [EAGAIN]. Also, if a request is greater than PIPE_BUF bytes and all data previously written to the pipe has been read, writev( ) transfers at least PIPE_BUF bytes.

When attempting to write to a socket with no space available for data:

If the O_NONBLOCK flag is not set, the writev( ) function blocks until space becomes available.

If the O_NONBLOCK flag is set, the writev( ) function returns the value -1 and sets

errno to [EAGAIN]. The O_NONBLOCK flag has no effect if there is space available.

527186-003 Hewlett-Packard Company 10

19

writev(2) OSS System Calls Reference Manual

Upon successful completion, the writev( ) function marks the st_ctime and st_mtime fields of the file for update and clears the set-user-ID and set-group-ID attributes if the file is a regular file.

The fcntl( ) function provides more information about record locks.

If it is interrupted by a signal before it writes any data, the writev( ) function returns the value -1 with errno set to [EINTR]. If it is interrupted by a signal after it has successfully written some data, the writev( ) function returns the number of bytes that it has written.

Use on Guardian Objects

Attempting to write to a Guardian file (that is, a file in /G) that is locked causes the writev( ) function to return -1 and set errno to [EGUARDIANLOCKED].

RETURN VALUES

Upon successful completion, the writev( ) function returns the number of bytes that were actually written. Otherwise, the value -1 is returned, and errno is set to indicate the error.

ERRORS

If any of these conditions occurs, the writev( ) function sets errno to the corresponding value:

[EAGAIN] One of these conditions occurred:

An attempt was made to write to a file descriptor that cannot accept data, and the O_NONBLOCK flag is set.

A write to a pipe (FIFO file) of PIPE_BUF bytes or less is requested,

O_NONBLOCK is set, and not enough free space is available.

The O_NONBLOCK flag is set on this file, and the process would be delayed in the write operation.

[EBADF] The filedes parameter is not a valid file descriptor open for writing.

[ECONNRESET]

One of these conditions occurred:

The transport-provider process for this socket is no longer available.

The TCP/IP subsystem for this socket is no longer available.

The connection was forcibly closed by the peer socket.

The file descriptor specified by the filedes parameter can only be closed.

[EFAULT] Part of the iov parameter points to a location outside of the allocated address space of the process.

[EFBIG] An attempt was made to write a file that exceeds the maximum file size.

[EGUARDIANLOCKED]

A writev( ) operation was attempted to a file in the Guardian file system (that is, a file in /G) that is locked.

[EINTR]

[EINVAL]

A writev( ) operation was interrupted by a signal before any data was written.

One of these conditions occurred:

The file position pointer associated with the file specified by the filedes parameter was negative.

The value of the iov_count parameter was less than or equal to 0 (zero), or greater than IOV_MAX.

10

20 Hewlett-Packard Company 527186-003

System Functions (w) writev(2)

[EIO]

One of the iov_len values in the iov array was negative or overflowed a data item of type ssize_t.

The sum of the iov_len values in the iov array overflowed an integer.

One of these conditions occurred:

The process is a member of a background process group attempting to write to its controlling terminal, the TOSTOP flag is set, the process is neither ignoring nor blocking the SIGTTOU signal, and the process group of the process is orphaned.

A physical I/O error occurred. The device holding the file might be in the down state, or both processors that provide access to the device might have failed. Data might have been lost during a transfer.

[EISGUARDIAN]

The value used for the filedes parameter is appropriate only in the Guardian environment.

[ENETDOWN]

The filedes parameter specifies a file on a remote HP NonStop node, but communication with the remote node has been lost.

[ENOSPC] No free space is left on the fileset containing the file.

[ENOTCONN] An attempt was made to write to a socket that is not connected to a peer socket.

[ENXIO] One of these conditions occurred:

The device associated with the file descriptor specified by the filedes parameter is a block special device or character special file, and the file pointer is out of range.

No existing device is associated with the file descriptor specified by the

filedes parameter.

[EPIPE] One of these conditions occurred:

An attempt was made to write to a pipe or FIFO file that is not open for reading by any process. A SIGPIPE signal is sent if the process is running in the OSS environment.

An attempt was made to write to a pipe that has only one end open.

An attempt was made to write to a socket that is shut down or closed.

[ETIMEDOUT]

Data transmission on the socket timed out.

[EWRONGID] One of these conditions occurred:

The process attempted an input or output operation through an operating system input/output process (such as a terminal server process) that has failed or is in the down state.

527186-003 Hewlett-Packard Company 10

21

writev(2) OSS System Calls Reference Manual

The processor for the disk process of the specified file failed during an input or output operation, and takeover by the backup process occurred.

The open file descriptor has migrated to a new processor but the new processor lacks a resource or system process needed for use of the file descriptor.

The file descriptor specified by the filedes parameter can only be closed.

For all other error conditions, errno is set to the appropriate Guardian file-system error number.

See the Guardian Procedure Errors and Messages Manual for more information about a specific

Guardian file-system error.

RELATED INFORMATION

Functions: creat(2), fcntl(2), lseek(2), open(2), pipe(2), socket(2), ulimit(3).

STANDARDS CONFORMANCE

The HP implementation does not:

Return the errno value [EWOULDBLOCK] for a call on a socket that does not have

O_NONBLOCK set and does not have space available to receive data

Generate the SIGXFSZ signal

HP extensions to the XPG4 Version 2 specification are:

The errno values [ECONNRESET], [EFAULT], [EGUARDIANLOCKED], [EINVAL],

[ENETDOWN], [ENOTCONN], [ETIMEDOUT], and [EWRONGID] can be returned.

10

22 Hewlett-Packard Company 527186-003

Section 11. Files

This section contains reference pages for some Open System Services (OSS) header files and special files. These reference pages reside in the cat4 and cat7 directories and are sorted alphabetically by U.S. English conventions in this section.

527186-003 Hewlett-Packard Company 11

1

ar(4) OSS System Calls Reference Manual

NAME

ar - Describes the archive (library) file format

SYNOPSIS

#include <ar.h>

DESCRIPTION

The ar archive command combines several files into one. Archives are used mainly as libraries to be searched by the Binder utility for TNS or accelerated programs and by the nld utility for

TSN/R native programs.

A file produced by the ar command has a magic number at the start, followed by the constituent files, each preceded by a file header. The magic number and header layout are described in the

ar.h header file.

Each file begins on an even boundary. A newline character is inserted between files if necessary; nevertheless, the size given reflects the actual size of the file exclusive of padding.

There is no provision for empty areas in an archive file.

The encoding of the header is portable across machines. If an archive contains printable files, the archive itself is printable.

The header is made up of six fixed-length ASCII fields, followed by a 2-character trailer. The fields are as follows:

ar_name ar_date ar_uid ar_gid ar_mode ar_size

Object name (16 characters)

File’s last modification time (12 characters); for example, UTC seconds since the

Epoch

User ID (6 characters)

Group ID (6 characters)

File’s mode (8 characters)

File’s size (10 characters)

All numeric fields are in decimal, except for the file mode, which is in octal.

The 2-byte trailer is the string

`\n

Only the ar_name field provides for overflows. If any filename is more than 16 characters in length or contains an embedded space, the string

#1/ followed by the ASCII length of the filename, is written in the ar_name field. The file size

(stored in the archive header) is incremented by the length of the filename. The filename is then written immediately following the archive header.

RELATED INFORMATION

Commands: ar(1), nm(1).

11

2 Hewlett-Packard Company 527186-003

Files core(4)

NAME

core, saveabend - Is a file containing a memory image

DESCRIPTION

In the OSS implementation, the equivalent of a core file is a saveabend file. A saveabend file is a type of process snapshot file and can be used with a system debugger when necessary.

A saveabend file is created whenever a process terminates abnormally and it is possible to create a saveabend file. The location of a saveabend file is displayed on the home terminal of the terminated process.

A saveabend file is created according to the following naming convention:

ZZSAnnnn where nnnn is a numeric increment.

The saveabend file contains data-area and file-status information at the time of the failure. Use a symbolic debugger program to examine the saveabend file. Refer to the appropriate manual for the symbolic debugger for information on saveabend files and how to examine them.

NOTES

There is no core.h header file.

Saveabend files are sometimes referred to as Guardian save or SAVEABEND files.

RELATED INFORMATION

Commands: c89(1), gtacl(1), osh(1), run(1), runv(1), sh(1).

Functions: sigaction(2), tdm_execve(2), tdm_execvep(2), tdm_spawn(2), tdm_spawnp(2).

Files: signal(4).

527186-003 Hewlett-Packard Company 11

3

cpio(4) OSS System Calls Reference Manual

NAME

cpio - Describes the extended cpio archive file format

SYNOPSIS

#include <cpio.h>

DESCRIPTION

The byte-oriented cpio archive file format is a series of entries, each entry made up of a header that describes the file and the name of the file, followed by the contents of the file.

The format of the cpio header is described below.

Table 11

1. cpio Archive File Header Format

Header Field c_magic c_dev c_ino c_mode c_uid c_gid c_nlink c_rdev c_mtime c_namesize c_filesize

Length (in octets)

6

6

6

6

6

6

6

6

11

6

11

Interpretation

Octal number

Octal number

Octal number

Octal number

Octal number

Octal number

Octal number

Octal number

Octal number

Octal number

Octal number

Contents

Identifies the archive as transportable by containing the value 070707

ID of the device containing the file

File serial number

File type and access permission

User ID of the owner

Group ID of the owner

Number of links referencing the file at the time the archive was created

Not used

Latest modification time of the file at the time the archive was created

Length of the pathname, including the terminating null character

Byte length of the file data

11

4 Hewlett-Packard Company 527186-003

Files cpio(4)

The archive entry for the name of a file has the following format:

Table 11

2. cpio Archive File Filename Entry Format

Field Name Length (in octets) Interpretation c_name c_namesize

Pathname string

The c_name field contains the pathname of the file as a string with the length given by the

c_namesize field in the file header. This string length includes the null character that terminates the name. If the filename is found on a medium that would create an invalid pathname, the pax utility skips the file and displays an error message to the standard error file.

Following the header and the pathname string, the cpio archive file data has the following form:

Table 11

3. cpio Archive File Data Format

Field Name Length (in octets) Interpretation c_filedata c_filesize

Data

If the c_filesize field of the header has the value 0 (zero), then the file is empty.

A header denoting the filename TRAILER!!! indicates the end of the archive; what follows this header is undefined.

Only regular files contain data that can be restored. FIFO special files, directories, and the trailer are archived with the c_filesize field of the header equal to 0 (zero); these objects are restored with the pax utility as directories and FIFOs.

527186-003 Hewlett-Packard Company 11

5

cpio(4) OSS System Calls Reference Manual

The cpio.h header file contains the following macro definitions:

Table 11

4. cpio.h Header File Macros

C_IRUSR

C_IWUSR

C_IXUSR

C_IRGRP

C_IWGRP

C_IXGRP

C_IROTH

C_IWOTH

C_IXOTH

C_ISUID

C_ISGID

C_ISVTX

C_ISDIR

C_ISFIFO

C_ISREG

C_ISBLK

C_ISCHR

C_ISCTG

C_ISLNK

C_ISSOCK

MAGIC

RELATED INFORMATION

Commands: pax(1), pinstall(1).

Value (in octal) Interpretation

0000400

0000200

0000100

0000040

0000020

0000010

0000004

0000002

0000001

0004000

0002000

0001000

0040000

0010000

0100000

0060000

0020000

0110000

0120000

0140000

070707

Read by owner

Write by owner

Execute by owner

Read by group

Write by group

Execute by group

Read by others

Write by others

Execute by others

Set user ID

Set group ID

Reserved

Directory

FIFO

Regular file

Block special file

Character special file

Reserved

Reserved

Reserved

Magic number value

11

6 Hewlett-Packard Company 527186-003

Files dir(4)

NAME

dir - Describes the format of directories

SYNOPSIS

#include <sys/types.h>

#include <dirent.h>

DESCRIPTION

A directory is a file that contains directory entries. The fact that a file is a directory is indicated by a bit in the flag word of the inode entry for the file.

Users cannot write a directory. Users can read directory entries by making calls to the readdir( ) function after opening the directory file by calling the opendir( ) function.

Directory entries are returned in directory entry structures, which are of variable length. Each directory entry has a dirent structure at the beginning, containing its inode number, the length of the entry, and the length of the filename contained in the entry. These structure components are followed by the filename, padded to a 4-byte boundary with null bytes. All names are guaranteed null-terminated. The maximum permitted length of a name in a directory can be obtained by calling the pathconf() function.

By convention, the first two entries in each directory are for . (dot) and . . (dot-dot). The . (dot) entry is for the directory itself. The . . (dot-dot) entry is for the parent directory. The meaning of

. . (dot-dot) is modified for the / (root) directory of the OSS file system, where . . (dot-dot) has the same meaning as . (dot).

Guardian directories (that is, directories within the /G file system) behave the same as OSS directories, with the following exceptions:

The mkdir( ) function successfully creates a directory within /G only when all of the following are true:

— The directory is exactly three directories under the root (for example,

/G/vol/subvol).

— The filenames in the directory pathname use correct Guardian naming syntax

(otherwise, errno is set to [EINVAL]).

— The directory corresponds to a Guardian subvolume.

The mkdir( ) function succeeds on a directory that is an existing Guardian subvolume

(for example, /G/vol/subvol) only when the Guardian subvolume is empty. If the Guardian subvolume is not empty, the mkdir( ) function fails and errno is set to the value

[EEXIST].

RELATED INFORMATION

Functions: chdir(2), closedir(3), mkdir(2), opendir(3), readdir(3), rewinddir(3), rmdir(2).

527186-003 Hewlett-Packard Company 11

7

float(4) OSS System Calls Reference Manual

NAME

float - Specifies the system limits for floating-point operations

SYNOPSIS

#include <float.h>

DESCRIPTION

The float.h header file defines symbolic names. These symbolic names represent floating-point values for the two possible floating-point formats that a program can use. The floating-point format is chosen at compilation time.

See the float.h header file for the actual values of these limits in the HP implementation.

The values shown in the following table depend on whether the process is using Tandem-format floating-point data (using the -WTandem_float c89 compiler flag or equivalent) or is using IEEE floating-point data (using the -WIEEE_float c89 compiler flag or equivalent).

11

8 Hewlett-Packard Company 527186-003

Files float(4)

Table 11

5. Values for Floating-Point Constants

Tandem-Format Value IEEE-Format Value

DBL_DIG

DBL_EPSILON

DBL_MANT_DIG

DBL_MAX

DBL_MAX_EXP

DBL_MAX_10_EXP

DBL_MIN

DBL_MIN_EXP

DBL_MIN_10_EXP

FLT_EPSILON

FLT_MANT_DIG

FLT_MAX

FLT_MAX_EXP

FLT_MAX_10_EXP

FLT_MIN

FLT_MIN_EXP

FLT_MIN_10_EXP

LDBL_DIG

LDBL_EPSILON

16

5.551115123125782720e-

17

55

1.15792089237316192e77

1.7976931348623157E+308

256

77 308

1.7272337110188889e-77 2.2250738585072014E-308

-254

-77

2.3841858e-17

23

1.1579208e77F

256

77

1.7272337e-77F

-254

-77

16

5.551115123125782720e-

17

15

2.2204460492503131E-16

53

1024

-1021

-307

1.19209290E-07F

24

3.40282347E+38F

128

38

1.17549435E-38F

-125

37

15

2.2204460492503131E-16

LDBL_MANT_DIG

LDBL_MAX

55

LDBL_MAX_EXP

256

LDBL_MAX_10_EXP

77

53

1.15792089237316192e77

1.7976931348623157E+308

1024

308

LDBL_MIN

LDBL_MIN_EXP

1.7272337110188889e-77

-254

LDBL_MIN_10_EXP

-77

2.2250738585072014E-308

-1021

-307

RELATED INFORMATION

Files: limits(4).

STANDARDS CONFORMANCE

This file conforms to the XPG4 version 2 specification when used for IEEE floating-point data.

Remember the following rules when using any special floating-point mode:

Do not assume that functions such as printf( ) or tanh( ) behave correctly if you call them after setting a nondefault mode (such as rounding toward zero). Unless a function is documented as tolerating such settings, you should restore the default operating mode before calling the function.

The exception bits of the status register stay set until they are explicitly cleared.

527186-003 Hewlett-Packard Company 11

9

limits(4) OSS System Calls Reference Manual

NAME

limits - Specifies the system limits

SYNOPSIS

#include <limits.h>

DESCRIPTION

The limits.h header file defines symbolic names. These symbolic names represent:

Implementation-dependent constants whose values set limits on system resources used by applications in the OSS environment. These values are all at least as large as minimum acceptable values set by the POSIX.1, POSIX.2, and XPG4 standards. See

Implementation-Dependent Constants, later in this reference page.

POSIX.1 and POSIX.2 minimum acceptable values. See POSIX-Defined Minimum

Values, later.

Floating-point values for the two possible floating-point formats that a program can use.

The floating-point format is chosen at compilation time.

See the limits.h header file for the actual values of these limits in the HP implementation.

Some of the implementation-dependent constants have values that can increase at run time.

These runtime values can be determined at run time using the sysconf( ) function.

Other limiting values are available only at run time for one of the following reasons:

The limit is pathname-dependent.

The limit differs between compile time and run time.

These values are not specified in the limits.h header file. For completeness, they are listed under

Values Unknown at Compile Time, later in this reference page.

An application can use the fpathconf( ), pathconf( ), and sysconf( ) functions to determine the actual value of any limit at run time.

Implementation-Dependent Constants

The following values are defined in the limits.h header file. Some of these values are minimum values that can increase at run time. Such values are indicated as "runtime-increasable."

BC_BASE_MAX

Maximum obase value allowed by the bc utility. This is a runtime-increasable value. Use the sysconf( ) function to obtain the runtime value.

BC_DIM_MAX

Maximum number of elements permitted in an array by the bc utility. This is a runtime-increasable value. Use the sysconf( ) function to obtain the runtime value.

BC_SCALE_MAX

Maximum scale value allowed by the bc utility. This is a runtime-increasable value. Use the sysconf( ) function to obtain the runtime value.

BC_STRING_MAX

Maximum length of a string constant accepted the bc utility. This is a runtimeincreasable value. Use the sysconf( ) function to obtain the runtime value.

11

10 Hewlett-Packard Company 527186-003

Files limits(4)

CHAR_BIT

Number of bits in an object of type char. This value is always 8.

CHARCLASS_NAME_MAX

Maximum number of bytes in a character class name. This value is always 255.

CHAR_MAX Maximum value for a signed char. In the HP implementation, the type char is not considered a signed integer; CHAR_MAX is therefore treated like

UCHAR_MAX.

CHAR_MIN

Minimum value for a signed char. In the HP implementation, the type char is not considered a signed integer; CHAR_MIN is therefore 0 (zero).

COLL_WEIGHTS_MAX

Maximum number of weights that can be assigned to an entry of the

LC_COLLATE order keyword in the locale definition file. This is a runtimeincreasable value. Use the sysconf( ) function to obtain the runtime value.

EXPR_NEST_MAX

Maximum number of expressions that can be nested within parentheses by the

expr utility. This is a runtime-increasable value. Use the sysconf( ) function to obtain the runtime value.

INT_BIT

Number of bits in an object of type int. In the HP implementation, this value is

32.

INT_MAX

Maximum value for an object of type int. This value depends on the size of an integer, which, in the HP implementation, is 32 bits.

INT_MIN

Minimum value for an object of type int. This value depends on the size of an integer, which, in the HP implementation, is 32 bits.

LINE_MAX

Unless otherwise noted, the maximum length, in bytes, of the input line to a utility (from either the standard input file or another file), when the utility is described as processing text files. The length includes room for the trailing newline character. This is a runtime-increasable value. Use the sysconf( ) function to obtain the runtime value.

LLONG_BIT Number of bits in an object of type long long int. This symbolic constant is specific to the HP implementation.

LLONG_MAX

Maximum value for an object of type long long int. This symbolic constant is specific to the HP implementation.

LLONG_MIN Minimum value for an object of type long long int. This symbolic constant is specific to the HP implementation.

LONG_BIT

Number of bits in an object of type long int.

LONG_MAX Maximum value for an object of type long int.

LONG_MIN

Minimum value for an object of type long int.

MB_LEN_MAX

Maximum number of bytes in a character for any supported locale.

527186-003 Hewlett-Packard Company 11

11

limits(4) OSS System Calls Reference Manual

NL_ARGMAX

Maximum value of the digit parameter in calls to the printf( ) and scanf( ) functions.

NL_MSGMAX

Maximum message number.

NL_NMAX

Maximum number of bytes in an N-to-1 collation mapping.

NL_SETMAX Maximum number of filesets per catalog.

NL_TEXTMAX

Maximum number of bytes in a message string.

PATH_MAX

Maximum number of bytes in a pathname including the terminating null character.

PIPE_BUF

Maximum number of bytes that is guaranteed to be transferred as a unit when writing to a pipe.

RE_DUP_MAX

Maximum number of repeated occurrences of a regular expression permitted when using the m,n interval notation. This is a runtime-increasable value. Use the sysconf( ) function to obtain the runtime value.

SCHAR_MAX

Maximum value for an object of type signed char.

SCHAR_MIN Minimum value for an object of type signed char.

SHRT_MAX

Maximum value for an object of type short.

SHRT_MIN

Minimum value for an object of type short.

TZNAME_MAX

Maximum number of bytes supported for the name of a time zone (not of the TZ variable).

UCHAR_MAX

Maximum value for an object of type unsigned char.

UINT_MAX

Maximum value for an object of type unsigned int. This value depends on the size of an integer, which, in the HP implementation, is 32 bits.

ULLONG_MAX

Maximum value for an object of type unsigned long long int. This symbolic constant is specific to the HP implementation.

ULONG_MAX

Maximum value for an object of type unsigned long int.

USHRT_MAX

Maximum value for an object of type unsigned short int.

WORD_BIT

Number of bits in a word of type int.

11

12 Hewlett-Packard Company 527186-003

Files limits(4)

POSIX-Defined Minimum Values

The symbolic constants in the following list are defined in the limits.h header file with values specified by the POSIX.1 and POSIX.2 standards or in the POSIX.12 draft standard. These symbolic names represent the most restrictive value for certain features. A portable application must not require a larger value for correct operation. The HP implementation defines some of the related symbolic constants to be less restrictive.

These values are the same in all POSIX-compliant implementations.

_POSIX_ARG_MAX

Maximum length in bytes of argument data to a function in the exec and

tdm_exec sets of functions, including environment data.

_POSIX_CHILD_MAX

Maximum number of simultaneous processes per real user ID.

_POSIX_FD_SETSIZE

Maximum number of file descriptors that the process can use with the select( ) function.

_POSIX_HIWAT

Maximum number of bytes that a process can buffer on a socket for a send or receive action.

_POSIX_LINK_MAX

Maximum number of links to a single file.

_POSIX_MAX_CANON

Maximum number of bytes in a terminal canonical input queue.

_POSIX_MAX_INPUT

Maximum number of bytes allowed in a terminal input queue.

_POSIX_NAME_MAX

Maximum number of bytes in a filename excluding the terminating null.

_POSIX_NGROUPS_MAX

Maximum number of simultaneous supplementary group IDs per process.

_POSIX_OPEN_MAX

Maximum number of files that a process can have open at a time.

_POSIX_PATH_MAX

Maximum number of bytes in a pathname including the terminating null.

_POSIX_PIPE_BUF

Maximum number of bytes that is guaranteed to be atomic when writing to a pipe.

_POSIX_QLIMIT

Maximum number of connections that the process can queue on a single socket.

_POSIX_SSIZE_MAX

Maximum value that can be stored in an object of type ssize_t.

527186-003 Hewlett-Packard Company 11

13

limits(4) OSS System Calls Reference Manual

_POSIX_STREAM_MAX

Maximum number of streams that one process can have open at one time.

_POSIX_TZNAME_MAX

Maximum number of bytes supported for the name of a time zone (not of the TZ variable).

_POSIX2_BC_BASE_MAX

Maximum obase values allowed by the bc utility.

_POSIX2_BC_DIM_MAX

Maximum number of elements permitted in an array by the bc utility.

_POSIX2_BC_SCALE_MAX

Maximum scale value allowed by the bc utility.

_POSIX2_BC_STRING_MAX

Maximum length of a string constant accepted by the bc utility.

_POSIX2_COLL_WEIGHTS_MAX

Maximum number of weights that can be assigned to an entry of the

LC_COLLATE order keyword in the locale definition file.

_POSIX2_EXPR_NEST_MAX

Maximum number of expressions that can be nested within parentheses by the

expr utility.

_POSIX2_LINE_MAX

Unless otherwise noted, the maximum length, in bytes, of the input line to a utility (from either the standard input file or another file), when the utility is described as processing text files. The length includes room for the trailing newline character.

_POSIX2_RE_DUP_MAX

Maximum number of repeated occurrences of a regular expression permitted when using the interval notation m,n.

Values Unknown at Compile Time

The following values are unknown at compile time and are therefore not defined in the limits.h header file:

ARG_MAX

Maximum length in bytes of argument data to a function in the exec, tdm_exec, and tdm_spawn sets of functions. Use the sysconf( ) function to obtain this value at run time.

CHILD_MAX Maximum number of simultaneous processes per real user ID. Use the sysconf( ) function to obtain this value at run time.

IOV_MAX

Maximum number of iovec structures that a process can use at a given time for scatter or gather operations. Use the sysconf( ) function to obtain this value at run time.

LINK_MAX

Maximum value of a file’s link count. Use the pathconf( ) function to obtain this value at run time.

11

14 Hewlett-Packard Company 527186-003

Files limits(4)

MAX_CANON

Maximum number of bytes in a terminal canonical input line. Use the path-

conf( ) function to obtain this value at run time.

MAX_INPUT Minimum number of bytes for which space is available in a terminal input queue; therefore, the maximum number of bytes a portable application can require to be entered as input before it reads them. Use the pathconf( ) function to obtain this value at run time.

NAME_MAX Maximum number of bytes in a filename (excluding the terminating null). Use the pathconf( ) function to obtain this value at run time.

NL_LANGMAX

Maximum number of bytes in a LANG name. Use the pathconf( ) function to obtain this value at run time.

OPEN_MAX Maximum number of files that one process can have open at any one time. Use the sysconf( ) function to obtain this value at run time.

SOCK_MAXBUF

Maximum number of bytes in a buffer to be used with a socket. Use the sys-

conf( ) function to obtain this value at run time.

STREAM_MAX

The number of streams that one process can have open at one time. Use the sys-

conf( ) function to obtain this value at run time.

Floating-Point Values

The values shown in the following table depend on whether the process is using HP floatingpoint data (using the -WTandem_float C compiler flag or equivalent) or is using IEEE floatingpoint data (using the -WIEEE_float C compiler flag or equivalent).

Table 11

6. Values for Floating-Point Constants

Tandem-Format Value IEEE-Format Value

DBL_DIG

DBL_MAX

FLT_MAX

16 15

1.15792089237316192e77

1.7976931348623157E+308

1.1579208e77F

3.40282347E+38F

RELATED INFORMATION

Functions: fpathconf(3), pathconf(3), sysconf(3).

Files: float(4).

STANDARDS CONFORMANCE

The HP implementation does not define ATEXIT_MAX, NZERO, PAGE_SIZE, PAGESIZE, or PASS_MAX.

The POSIX standards leave some features to the implementing vendor to define. The following features are affected in the HP implementation:

The following symbolic constants are assigned values that define limits above the maximum or below the minimum required by the XPG4 Version 2, POSIX.1, and POSIX.2

standards:

The XPG4 version 2 specification indicates that the floating-point symbolic constants

DBL_DIG, DBL_MAX, and FLT_MAX are to be withdrawn from the specification.

527186-003 Hewlett-Packard Company 11

15

limits(4) OSS System Calls Reference Manual

Table 11

7. Values for Symbolic Constants

POSIX-Defined Value OSS Value

CHARCLASS_NAME_MAX

14

CHAR_MAX

SCHAR_MAX (127) or

UCHAR_MAX (255)

CHAR_MIN

SCHAR_MIN (127) or 0

(zero)

COLL_WEIGHTS_MAX

INT_MAX

INT_MIN

LONG_MIN

MB_LEN_MAX

NGROUPS_MAX

NL_MSGMAX

NL_NMAX

NL_SETMAX

NL_TEXTMAX

2

32767

-32767

-2147483647

255

UCHAR_MAX (255)

0 (zero)

6

2147483647

-2147483647

-2147483648

1

0

4

32

32767 65535

No guaranteed minimum 10

255

_POSIX_LINE_MAX

(2048)

65535

8192

PATH_MAX

PIPE_BUF

SCHAR_MIN

SHRT_MIN

SSIZE_MAX

UINT_MAX

255

512

-127

-32767

32767

65535

1024

4096

-128

-32768

53248

4294967295

The following are HP extensions to the XPG4 Version 2 specification:

The values INT_BIT, LLONG_BIT, LLONG_MAX, and LLONG_MIN.

The sockets-related values _POSIX_FD_SETSIZE, _POSIX_HIWAT,

_POSIX_QLIMIT, and SOCK_MAXBUF.

11

16 Hewlett-Packard Company 527186-003

Files math(4)

NAME

math - Specifies the mathematical constants

SYNOPSIS

#include <math.h>

DESCRIPTION

The math.h header file defines symbolic names and constant values of type double.

The symbolic names are:

HUGE_VAL

Specifies a positive double expression that cannot necessarily be represented as a type float value. Used as an error indicator when returned as a value for mathematics library functions.

For Tandem-format floating-point data, the value of HUGE_VAL is

DBL_MAX. For IEEE floating-point data, the value of HUGE_VAL is positive infinity of type double.

MAXFLOAT Specifies the value of the maximum noninfinite single-precision floating-point number.

For Tandem-format floating-point data, the value of MAXFLOAT is

DBL_MAX. For IEEE floating-point data, the value of MAXFLOAT is also

DBL_MAX, but the value of DBL_MAX differs between the two formats.

Refer to the float(4) reference page for more information about DBL_MAX.

The following constants of type double are accurate within the precision of the double type:

M_E

M_LN2

M_LN10

Specifies the value of e.

Specifies the value of log to the base e of 2.

Specifies the value of log to the base e of 10.

M_LOG2E

Specifies the value of log to the base 2 of e.

M_LOG10E

Specifies the value of log to the base 10 of e.

M_PI

M_PI_2

Specifies the value of pi.

Specifies the value of pi divided by 2.

M_PI_4

Specifies the value of pi divided by 4.

M_SQRT2

Specifies the value of the square root of 2.

M_SQRT1_2 Specifies the value of 1 divided by the square root of 2.

M_1_PI

Specifies the value of 1 divided by pi.

M_2_PI

Specifies the value of 2 divided by pi.

M_2_SQRTPI Specifies the value of 2 divided by the square root of pi.

RELATED INFORMATION

Files: float(4).

527186-003 Hewlett-Packard Company 11

17

null(7)

NAME

null - Is a data sink file

SYNOPSIS

/dev/null

DESCRIPTION

Data written on a null special file is discarded.

Reads from a null special file always return 0 (zero) bytes.

EXAMPLES

To create a zero-length file using the cat command, enter: cat > foo < /dev/null

OSS System Calls Reference Manual

11

18 Hewlett-Packard Company 527186-003

Files

NAME

saveabend - Is a file containing a memory image

DESCRIPTION

See the core(4) reference page.

saveabend(4)

527186-003 Hewlett-Packard Company 11

19

signal(4) OSS System Calls Reference Manual

NAME

signal - Contains definitions and variables used by signal functions

SYNOPSIS

#include <signal.h>

DESCRIPTION

The signal.h header file contains:

Declarations of symbolic constants used to refer to the signals that occur in the OSS environment.

Declarations for the sigset_t type and the sigaction structure. Note that G-series TNS or accelerated processes and all native processes use different declarations for sigset_t; all processes using the same sigset_t declaration must be of the same process type.

Declarations of additional symbolic constants used in signal handling:

SA_NOCLDSTOP

Indicates that the SIGCHLD signal should not be generated when a child process stops.

SIG_ABORT Requests that the process terminate abnormally when a specific signal is received.

SIG_DEBUG Requests that the process enter the debugger when a specific signal is received.

SIG_DFL

Requests default signal handling.

SIG_ERR

Indicates an error condition by reserving a return code for a certain class of functions. Such functions return a pointer to a function that takes an integer as a parameter and returns void.

SIG_IGN

Requests that signals be ignored.

Declarations of additional symbolic constants used by the sigprocmask( ) function for handling process signal masks:

SIG_BLOCK Requests a union of the current mask and a supplied value.

SIG_SETMASK

Creates a mask from the supplied value.

SIG_UNBLOCK

Requests a mask of the current mask less the supplied value.

Signal Generation and Delivery

A signal is said to be generated for (or sent to) a process when the event that causes the signal first occurs. Examples of such events include detection of hardware faults, timer expiration, and any operating system trap condition normally detectable by a TNS or accelerated Guardian process, in addition to terminal activity, or the invocation of the kill( ) function.

Note: Signals cannot be sent to a TNS or accelerated Guardian process.

Each process has an action to be taken in response to each signal defined by the system. A signal is said to be delivered to a process when the appropriate action for the process and signal is taken.

11

20 Hewlett-Packard Company 527186-003

Files

527186-003 Hewlett-Packard Company

signal(4)

A process can elect to ignore the delivery of some signals, while allowing the system to perform default actions upon the delivery of other signals. The system also allows processes to install process-specific signal-catching functions.

During the time between the generation of a signal and its delivery, the signal is said to be pending. Usually, this interval cannot be detected by an application.

However, a signal can be blocked from delivery to a process. If the action associated with a blocked signal is anything other than to ignore the signal, and if that signal is generated for the process, the signal remains pending until either it is unblocked or the action associated with it is set to ignore the signal. If the action associated with the blocked signal is to ignore the signal, and if that signal is generated for the process, it is unspecified whether the signal is discarded immediately upon generation or remains pending; applications should therefore not depend on whether the signal is discarded or remains pending.

Each process has a signal mask that defines the set of signals currently blocked from delivery to it. The signal mask for a process is initialized to that of its parent. The sigaction( ), sigproc-

mask( ), and sigsuspend( ) functions control the manipulation of the signal mask.

The determination of which action is taken in response to a signal is made at the time the signal is delivered, allowing for any changes since the time of generation. This determination is independent of the means by which the signal was originally generated.

If a subsequent occurrence of a pending signal is generated, it is discarded and only one instance of the same signal remains pending; however, because this action is likely to change in future releases, users should not rely on this behavior. The order in which pending signals are delivered to a process is unspecified and should not be relied upon.

When any stop signal (SIGSTOP, SIGTSTP, SIGTTIN, or SIGTTOU) is generated for a process, any pending SIGCONT signal for that process is discarded. Conversely, when SIGCONT is generated for a process, all pending stop signals for that process are discarded even if these signals are being caught.

When SIGCONT is generated for a process that is stopped, the process continues, even if the

SIGCONT signal is blocked or ignored. If SIGCONT is blocked and not ignored, it remains pending until either it is unblocked or a stop signal is generated for the process.

When SIGUNCP is generated, the action taken allows an H-series process to control what happens when the process does not offer frequent enough opportunities to synchronize blade elements. Either the process can call a user signal-handler function, or the following actions are defined:

SIG_ABORT The process terminates abnormally.

SIG_DEBUG The process enters the debugger so that an appropriate location for a voluntary rendezvous opportunity can be identified.

SIG_DFL

The signal is ignored by the process, but the system suspends the process until an

EMS event is generated for logging by the $ZLOG distributor.

SIG_IGN

The signal is ignored by the process and no EMS event is generated.

When a signal handler is invoked (which normally only happens to allow debugging), the process should call sigaction( ) to set SIG_IGN or SIG_DFL or simply return. It is undefined what happens if the signal is rearmed and siglongjmp( ) is called before the synchronization completes: the process might suspend or it might abend.

Signals reserve the last 1000 words of the user stack. When a SIGSTK signal is delivered, the system cuts back the stack to the start of the last 1000 words. If user data is present in the last

1000 words of the stack, that data is lost.

11

21

signal(4) OSS System Calls Reference Manual

The Signals

The following table lists each signal name and corresponding signal number and default action.

On receipt of one of these signals, the application can elect to:

Accept the default action; see Default Action, later in this reference page.

Ignore the signal; see Ignoring a Signal, later.

Catch the signal by invoking a signal-specific function; see Catching a Signal, later.

Note that the SIGKILL, SIGSTOP, and SIGABEND signals can neither be caught nor ignored.

Table 11

8. Signals

Name

SIGABEND

SIGABRT

SIGALRM

SIGCHLD

SIGCONT

SIGFPE

SIGHUP

SIGILL

SIGINT

SIGIO

SIGKILL

SIGLIMIT

SIGMEMERR

SIGMEMMGR

SIGNOMEM

SIGPIPE

SIGQUIT

SIGRECV

SIGSEGV

SIGSTK

SIGSTOP

SIGTERM

SIGTIMEOUT

SIGTSTP

SIGTTIN

SIGTTOU

SIGUNCP

Number

28

8

1

4

31

6

Terminate with saveabend

Terminate with saveabend

14 Terminate process

18 Discard signal

2

7

Continue execution

Terminate with saveabend

Terminate process

Terminate with saveabend

Terminate process

Discard signal

3

19

11

25

20

15

9

27

22

24

23

13

26

21

29

30

10

Terminate process

Terminate with saveabend

Terminate with saveabend

Terminate with saveabend

Terminate with saveabend

Terminate process

Terminate with saveabend

Discard signal

Terminate with saveabend

Terminate with saveabend

Stop process

Terminate process

Terminate process

Stop process

Stop process

Stop process

Discard signal

Description

Abnormal termination

Abort process

Alarm clock

Child has stopped or terminated

Continue execution

Arithmetic overflow

Hangup

Invalid instruction

Interrupt

Input/output possible or completed

Kill

Operating system limits trap

Uncorrectable memory error

Memory manager read error

No memory available

Write on a pipe, no one to read it

Quit

Message queued on $RECEIVE

(currently not used)

Invalid address reference

Stack overflow

Stop

Software termination signal

Process loop timer timeout

Interactive stop

Background read attempted from controlling terminal

Background write attempted to controlling terminal

Uncooperative process (H-series servers only)

11

22 Hewlett-Packard Company 527186-003

Files signal(4)

SIGURG

SIGUSR1

SIGUSR2

SIGWINCH

5

16

17

12

Discard signal

Terminate process

Terminate process

Discard signal

Urgent condition on I/O channel

User-defined signal 1

User-defined signal 2

Terminal device window size changed

For details of the process loop timer, see the SETLOOPTIMER procedure in the Guardian Pro-

cedure Calls Reference Manual.

Note: The process terminates and, where possible, a saveabend (core) file is created on generation of any signal if both of the following conditions are true:

The signal was generated as a result of something other than the kill( ) or raise( ) function.

Either the signal is blocked or ignored, or the process is in operating system code when the signal is generated.

The _POSIX_JOB_CONTROL symbolic constant is always defined. Hence, the job control signals are all supported: SIGCHLD, SIGCONT, SIGSTOP, SIGTSTP, SIGTTIN, and

SIGTTOU.

Default Action

The default action for a signal occurs when the signal is not blocked and one of the following is true:

No signal-catching function is installed for that signal.

A signal-catching function is installed for the signal, but the SIG_DFL action is specified.

The table under The Signals, earlier, indicates a default action for each signal. The default actions have the following meanings:

Terminate process

Terminate the receiving process with all the consequences described for the

_exit( ) function.

Terminate with saveabend

Terminate the receiving process with all the consequences described for the

_exit( ) function. Create a memory image file (saveabend file) in the current directory of the receiving process if the following conditions are met:

The effective user ID and the real user ID of the receiving process are equal.

A regular file named ZZSAnnnn (the saveabend file) can be created in the current directory. The file will have the following properties:

— The access permission code 0666 (0x1B6), modified by the filemode creation mask (see the umask(2) reference page)

— A file owner ID that is the same as the effective user ID of the receiving process

527186-003 Hewlett-Packard Company 11

23

signal(4) OSS System Calls Reference Manual

— A file group ID that is the same as the effective group ID of the receiving process

Note that the location of the saveabend file is different in the OSS environment than in the Guardian environment. In the Guardian environment, the file is created on the same subvolume as the program file. In the OSS environment, the file is created in the current working directory.

Saveabend files are known on most UNIX systems as core files.

Continue execution

Restart the receiving process if it is stopped, or ignore the signal if the process is already executing.

Stop process Stop the execution of the receiving process. When a process stops, a SIGCHLD signal is sent to its parent process, unless the parent process has set the

SA_NOCLDSTOP bit.

While a process is stopped, any additional signals that are sent to the process are not delivered until the process is continued. Exceptions to this are SIGKILL and

SIGABEND signals, which always terminate the receiving process. Any other signal that causes process termination causes the same result as SIGKILL or

SIGABEND except when they are blocked. The other exception is the

SIGCONT signal, which causes the receiving process to restart or continue running, even if the signal is blocked or ignored.

Discard signal Ignore the signal. Delivery of the signal has no effect on the receiving process.

If a signal action is set to the SIG_DFL value while the signal is pending, the signal remains pending.

Ignoring a Signal

A signal is ignored when a signal handler with the action set to SIG_IGN is installed for that signal.

Delivery of the signal has no effect on the receiving process.

Note that the SIGKILL, SIGSTOP, and SIGABEND signals cannot be ignored.

Catching a Signal

Upon delivery of a signal that is to be caught, the receiving process is to run a signal-catching function specified in either the sigaction( ) function call or the signal( ) function call. The signalcatching function can be declared as follows:

void handler(

int signal);

The signal parameter is the signal number.

A new signal mask is calculated and installed for the duration of the signal-catching function or until a sigprocmask( ) or sigsuspend( ) function call is made. This mask is formed by taking the union of the process signal mask, the mask associated with the action for the signal being delivered, and a mask corresponding to the signal being delivered.

The mask associated with the signal-catching function is not allowed to block those signals that cannot be ignored. The system enforces this rule without causing an error to be indicated. If and when the signal-catching function returns, the original signal mask is restored and the receiving process resumes execution at the point it was interrupted.

11

24 Hewlett-Packard Company 527186-003

Files signal(4)

The signal-catching function can cause the process to resume in a different context by calling the

longjmp( ) function. When the longjmp( ) function is called, the process reverts to the state saved by a corresponding call to the setjmp( ) function.

Once the sigaction( ) function installs an action for a specific signal, it remains installed until another action is explicitly requested by another call to the sigaction( ) function or until a function from the exec or tdm_exec sets of functions is called. Signal actions installed by the sig-

nal( ) function, however, are reset to the default action each time the signal is delivered.

If a signal action is set to a pointer to a function while the signal is pending, the signal remains pending.

When signal-catching functions are invoked asynchronously with process execution, the behavior of some of the functions is unspecified if they are called from a signal-catching function. The following is a list of functions that are reentrant. Therefore, applications can invoke these functions, without restriction, from signal-catching functions:

_exit( ) access( ) alarm( ) cfgetispeed( ) cfgetospeed( ) cfsetispeed( ) cfsetospeed( ) chdir( ) chmod( ) chown( ) close( ) creat( ) dup( ) dup2( ) execle( ) execve( ) fcntl( ) fork( ) fpathconf( ) fstat( ) getegid( ) geteuid( ) getgid( ) getgroups( ) getpgrp( ) getpid( ) getppid( ) getuid( ) kill() link( ) lseek( ) mkdir( ) mkfifo( ) open( ) pathconf( ) pause( ) pipe( ) raise( ) read( ) rename( ) rmdir( ) setgid( ) setsid( ) setuid( ) sigaction( ) sigaddset( ) sigdelset( ) sigemptyset( ) sigfillset( ) sigismember( ) signal( ) sigpending( ) sigprocmask( ) sigsuspend( ) sleep( ) stat( ) tdm_execvep( ) tdm_execvp( ) tdm_fork( ) tdm_spawn( ) tdm_spawnp( ) tcdrain( ) tcflow( ) tcflush( ) tcgetattr( ) tcgetprgp( ) tcsendbreak( ) tcsetattr( ) tcsetpgrp( ) time( ) times( ) umask( ) uname( ) unlink( ) utime( ) wait( ) waitpid( ) write( )

All other functions are considered to be unsafe with respect to signals and should not be called from a signal-catching function, because their behavior is undefined.

On successful return from a signal-catching function for a SIGFPE, SIGILL, SIGLIMIT,

SIGMEMERR, SIGMEMMGR, SIGNOMEM, SIGSEGV, or SIGSTK signal that was not generated by a kill( ) or raise( ) function call, a process receives a SIGABEND signal and terminates with a Guardian condition code of -11. A process deletion (-101) Guardian system message is sent to the mom, ancestor, or job ancestor of the terminated process and indicates abnormal termination.

No SIGCHLD signal is generated if a process establishes a signal-catching function for the

SIGCHLD signal while the process has a terminated child process for which it has not waited.

RELATED INFORMATION

Functions: kill(2), longjmp(3), raise(3), setjmp(3), sigaction(2), sigaddset(3), sigdelset(3),

sigemptyset(3), sigfillset(3), sigismember(3), siglongjmp(3), signal(3), sigpending(2), sigproc-

mask(2), sigsetjmp(3), sigsuspend(2), sigwait(2).

527186-003 Hewlett-Packard Company 11

25

signal(4) OSS System Calls Reference Manual

STANDARDS CONFORMANCE

The HP implementation does not provide the following signals defined in the XPG4 Version 2 specification:

SIGBUS, SIGPOLL, SIGPROF, SIGSYS, SIGTRAP, SIGVTALRM, SIGXCPU, and

SIGXFSZ.

The POSIX standards leave some features to the implementing vendor to define. The following features are affected in the HP implementation:

HP-specific signals are supported; see the extensions listed later.

The _POSIX_JOB_CONTROL symbolic constant is always defined. Hence, the job control signals are all supported: SIGCHLD, SIGCONT, SIGSTOP, SIGTSTP,

SIGTTIN, and SIGTTOU.

On generation of a blocked signal, it is unspecified whether the signal is discarded or remains pending when the associated action is to ignore the signal.

Only one instance of the same signal can remain pending for a process. Subsequent occurrences of the same signal are discarded. However, this action is likely to change in a future release, so users should not depend on it.

The order in which pending signals are delivered to a process is unspecified and should not be relied upon.

Signals are generated for all operating system trap conditions normally detectable in the

Guardian environment.

After ignoring a SIGFPE, SIGILL, SIGLIMIT, SIGMEMERR, SIGMEMMGR,

SIGNOMEM, SIGSEGV, or SIGSTK signal that was not generated by a kill( ) or

raise( ) function, a process terminates. Similarly, after returning from a signal-catching function for one occurrence of such a signal, a process receives a SIGABEND signal and terminates with a Guardian condition code of -11. A process deletion (-101) Guardian system message is sent to the mom, ancestor, or job ancestor of the terminated process and indicates abnormal termination.

No SIGCHLD signal is generated if a process establishes a signal-catching function for the SIGCHLD signal while the process has a terminated child process for which it has not waited.

The following are HP extensions to the XPG4 Version 2 specification:

The following signals are HP extensions: SIGABEND, SIGIO, SIGLIMIT, SIGME-

MERR, SIGMEMMGR, SIGNOMEM, SIGRECV, SIGSTK, SIGTIMEOUT,

SIGWINCH, and SIGUNCP.

11

26 Hewlett-Packard Company 527186-003

Files spthread.h(4)

NAME

spthread.h - Thread-aware header file

SYNOPSIS

#include <spthread.h>

DESCRIPTION

The <spthread.h> header file contains the standard POSIX threads library API definitions. For reference, this reference page also documents the nonstandard POSIX extensions, thread-aware functions, thread-aware toolkit APIs, and thread-aware $RECEIVE APIs that are implemented in

T1248 POSIX threads.

Standard POSIX Threads Library APIs

The following are the standard POSIX threads library API definitions included in T1248 POSIX threads:

int pthread_atfork( pthread_void_fn_ptr_t, pthread_void_fn_ptr_t, pthread_void_fn_ptr_t ); int pthread_attr_destroy( pthread_attr_t * ); int pthread_attr_getdetachstate( const pthread_attr_t *, int * ); int pthread_attr_getinheritsched( const pthread_attr_t *, int * ); int pthread_attr_getschedparam( const pthread_attr_t *, struct sched_param * ); int pthread_attr_getschedpolicy( const pthread_attr_t *, int * ); int pthread_attr_getstackaddr( const pthread_attr_t *, void ** ); int pthread_attr_getstacksize( const pthread_attr_t *, size_t * ); int pthread_attr_init( pthread_attr_t * ); int pthread_attr_setdetachstate( pthread_attr_t *, int ); int pthread_attr_setinheritsched( pthread_attr_t *, int ); int pthread_attr_setschedparam( pthread_attr_t *,const struct sched_param * ); int pthread_attr_setschedpolicy( pthread_attr_t *, int ); int pthread_attr_setstacksize( pthread_attr_t *, size_t ); int pthread_cancel( pthread_t ); void pthread_cleanup_pop( int );

527186-003 Hewlett-Packard Company 11

27

spthread.h(4) OSS System Calls Reference Manual void pthread_cleanup_push( void ( * ) ( void * ), void * ); int pthread_cond_broadcast( pthread_cond_t * ); int pthread_cond_destroy( pthread_cond_t * ); int pthread_cond_init( pthread_cond_t *, const pthread_condattr_t * ); int pthread_cond_signal( pthread_cond_t * ); int pthread_cond_timedwait( pthread_cond_t *, pthread_mutex_t *, const struct timespec * ); int pthread_cond_wait( pthread_cond_t *, pthread_mutex_t * ); int pthread_condattr_destroy( pthread_condattr_t * ); int pthread_condattr_init( pthread_condattr_t * ); int pthread_create( pthread_t *, const pthread_attr_t *, pthread_startroutine_t, pthread_addr_t ); int pthread_detach( pthread_t ); void pthread_equal( thread1, thread2 ); void pthread_exit( pthread_addr_t ); int pthread_getschedparam( pthread_t, int *, struct sched_param * ); void * pthread_getspecific( pthread_key_t ); int pthread_join( pthread_t, pthread_addr_t * ); int pthread_key_create( pthread_key_t *, pthread_destructor_t ); int pthread_key_delete( pthread_key_t ); int pthread_kill( pthread_t, int ); int pthread_mutexattr_destroy( pthread_mutexattr_t * ); int pthread_mutexattr_init( pthread_mutexattr_t * ); int pthread_mutex_destroy( pthread_mutex_t * ); int pthread_mutex_init( pthread_mutex_t *, const pthread_mutexattr_t * ); int pthread_mutex_lock( pthread_mutex_t * ); int pthread_mutex_trylock( pthread_mutex_t * ); int pthread_mutex_unlock( pthread_mutex_t * );

11

28 Hewlett-Packard Company 527186-003

Files int pthread_once( pthread_once_t *, pthread_initroutine_t ); pthread_t pthread_self( void ); int pthread_setcancelstate( int, int * ); int pthread_setcanceltype( int, int * ); int pthread_setschedparam( pthread_t, int, const struct sched_param * ); int pthread_setspecific( pthread_key_t, pthread_addr_t ); int pthread_sigmask( int, const sigset_t *, sigset_t * ); void pthread_testcancel( void );

Nonstandard POSIX API Definitions

The following are the nonstandard POSIX API definitions:

int pthread_attr_getguardsize_np( pthread_attr_t *, size_t * ); int pthread_attr_setguardsize_np( pthread_attr_t *, size_t ); int pthread_cond_signal_int_np( pthread_cond_t * ); int pthread_delay_np( struct timespec *interval ); int pthread_getattr_np( const pthread_t, pthread_attr_t ** ); int pthread_getconcurrency( void ); int pthread_getcontext_np( pthread_t target, ucontext_t *ucp ); int pthread_get_expiration_np( struct timespec *, struct timespec * ); int pthread_lock_global_np( void ); int pthread_mutexattr_getkind_np( pthread_mutexattr_t ); int pthread_mutexattr_setkind_np( pthread_mutexattr_t *, int ); int pthread_setconcurrency( int new_level ); int pthread_signal_to_cancel_np( sigset_t *, pthread_t * ); int pthread_unlock_global_np( void ); pid_t spt_fork( void ); int spt_getTMFConcurrentTransactions( void ); int spt_setTMFConcurrentTransactions( short ); spthread.h(4)

527186-003 Hewlett-Packard Company 11

29

spthread.h(4) OSS System Calls Reference Manual short SPT_ABORTTRANSACTION( void ); short SPT_BEGINTRANSACTION( long * transaction_tag ); short SPT_ENDTRANSACTION( void ); short SPT_RESUMETRANSACTION( long transaction_tag ); short SPT_SERVERCLASS_DIALOG_BEGIN_ ( long *dialogId, char * pathmon, short pathmonbytes, char * serverclass, short serverclassbytes, char * messagebuffer, short requestbytes, short maximumreplybytes, short * actualreplybytes, long timeout, short flags, short * scsoperationnumber, long tag ); short SPT_SERVERCLASS_DIALOG_SEND_ ( long dialogId, char * messagebuffer, short requestbytes, short maximumreplybytes, short * actualreplybytes, long timeout, short flags, short * scsoperationnumber, long tag ); short SPT_SERVERCLASS_DIALOG_END_ ( long dialogId ); short SPT_SERVERCLASS_DIALOG_ABORT_ ( long dialogId ); short SPT_SERVERCLASS_SEND_INFO_ ( short * serverclasserror, short * filesystemerror ); short SPT_SERVERCLASS_SEND_ ( char * pathmon, short pathmonbytes, char * serverclass, short serverclassbytes, char * messagebuffer, short requestbytes, short maximumreplybytes, short * actualreplybytes, long timeout, short flags, short * scsoperationnumber, long tag ); short SPT_TMF_GetTxHandle(

SPT_TMF_TxHandle_t *tx_handle ); short SPT_TMF_Init( void ); short SPT_TMF_SetTxHandle(

SPT_TMF_TxHandle_t *tx_handle ); spt_error_t spt_regPathsendFile( const short ); spt_error_t spt_regPathsendTagHandler( const long, spt_FileIOHandler_p, void * ); spt_error_t spt_unregPathsendTagHandler( const long );

11

30 Hewlett-Packard Company 527186-003

Files spthread.h(4) int spt_sigaction( int, const struct sigaction *, struct sigaction * ); unsigned int spt_sleep( unsigned int ); int spt_usleep( unsigned int ); int spt_pause( ); int spt_sigpending( sigset_t * ); int spt_sigsuspend( const sigset_t * ); int spt_sigwait( sigset_t *, int * );

Thread-Aware Function Definitions

If invoking a thread-aware function using the corresponding native UNIX function, first define

SPT_THREAD_AWARE. For example, after defining SPT_THREAD_AWARE, the function

printf will resolve to the nonblocking function spt_printf.

The following are the nonstandard POSIX, HP-implemented thread-aware function definitions:

int spt_accept( int socket, struct sockaddr *address, size_t *address_len ); int spt_close( int filedes ); int spt_connect( int socket, const struct sockaddr *address, size_t address_len ); int spt_fclose( FILE *stream ); int spt_fflush( FILE *stream ); int spt_fgetc( FILE *stream ); char *spt_fgets( char *string, int n, FILE *stream ); int spt_fgetwc( FILE *stream ); int spt_fprintf( FILE *stream, const char *format, ... ); int spt_fputc( int c, FILE *stream ); int spt_fputs( const char *string, FILE *stream ); wint_t spt_fputwc( wint_t c, FILE *stream ); ssize_t spt_fread( void *pointer, size_t size, size_t num_items, FILE *stream ); ssize_t spt_fwrite( const void *pointer, size_t size, size_t num_items, FILE *stream ); int spt_getc( FILE *stream ); int spt_getchar( void );

527186-003 Hewlett-Packard Company 11

31

spthread.h(4) int spt_gets( FILE *stream ); int spt_getw( FILE *stream ); wint_t spt_getwc( FILE *stream ); wint_t spt_getwchar( void ); int spt_printf( const char *format, ... ); int spt_putc( int c, FILE *stream ); int spt_putchar( int c ); int spt_puts( const char *string ); int spt_putw( int c, FILE *stream ); wint_t spt_putwc( wint_t c, FILE *stream ); wint_t spt_putwchar( wint_t c ); ssize_tvspt_readv( int filedes, struct iovec *iov, int iov_count ); ssize_t spt_recv( int socket, void *buffer, size_t length, int flags ); ssize_t spt_recvfrom( int socket, void *buffer, size_t length,int flags, struct sockaddr *address, size_t *address_len ); ssize_t spt_recvmsg( int socket, struct msghdr *message, int flags ); int spt_select( int nfds, fd_set *readfds, fd_set *writefds, fd_set *errorfds, struct timeval *timeout ); ssize_t spt_send( int socket, const void *buffer, size_t length, int flags ); ssize_t spt_sendmsg( int socket, const struct msghdr *message, int flags ); ssize_t spt_sendto( int socket, const void *buffer, size_t length, Lint flags, const struct sockaddr *dest_addr, size_t dest_len ); int spt_vfprintf(

FILE *stream, const char *format, va_list printarg );

OSS System Calls Reference Manual

11

32 Hewlett-Packard Company 527186-003

Files int spt_vprintf( const char *format, va_list printarg ); pid_t spt_waitpid( pid_t pid, int *stat_loc, int options ); ssize_t spt_write( int filedes, void *buffer, size_t nbytes ); ssize_t spt_writev( int filedes, struct iovec *iov, int iov_count );

Thread-Aware Toolkit API Extensions

The following are the thread-aware toolkit API definitions:

int spt_fd_read_ready( const int fd, struct timeval *timeout ); int spt_fd_write_ready( const int fd, struct timeval *timeout ); long spt_generateTag( void ); spt_error_t spt_interrupt( const short filenum, const spt_error_t errorSPT ); spt_error_t spt_interruptTag( const short filenum, const long tag, const, spt_error_t errorSPT ); spt_error_t spt_regFile( const short filenum ); spt_error_t spt_regFileIOHandler( const short filenum, const spt_FileIOHandler_p functionPtr ); spt_error_t spt_regOSSFileIOHandler( const int filedes, const spt_OSSFileIOHandler_p functionPtr ); spt_error_t spt_regTimerHandler( const spt_TimerHandler_p functionPtr ); spt_error_t spt_setOSSFileIOHandler( const int filedes, const int read, const int write, const int error ); spt_error_t spt_unregFile( const short filenum ); spt_error_t spt_unregOSSFileIOHandler( const int filedes );

Thread-Aware $RECEIVE API Definitions

The following are the thread-aware $RECEIVE API definitions:

long spt_INITRECEIVE( const short filenum, const short receive_depth ); long spt_RECEIVEREAD( const short filenum, char *buffer, const short read_count, long *count_read, const long timelimit, short *receive_info, short *dialog_info );

527186-003 Hewlett-Packard Company

spthread.h(4)

11

33

spthread.h(4) long spt_REPLYX( const char *buffer, const short write_count, short *count_written, const short msg_tag, const short error_return );

OSS System Calls Reference Manual

11

34 Hewlett-Packard Company 527186-003

Files tar(4)

NAME

tar - Describes the extended tar archive file format

SYNOPSIS

#include <tar.h>

DESCRIPTION

tar archives are created by the tar command. These archives are standardized and suitable for porting between different systems.

An extended tar archive or file consists of a series of blocks. Each block is a fixed size of 512 bytes.

Each file within the archive is represented by a header block and zero or more data blocks that contain the contents of the file. The header block describes the file. There are two blocks filled with binary zeros at the end of the archive as the end-of-archive indicator.

The data blocks are grouped for physical I/O. Each group of blocks is written with a single

write( ) operation. On magnetic tape, the result of this write is a single tape record.

The number of blocks in a group is set by the -b flag of the tar command; the default value is 20 blocks. The last group is always written at the full size, so blocks following the two zero blocks contain undefined data.

The header block is structured as shown in the following table. All lengths and offsets are in decimal.

Table 11

9. tar Archive File Header Block

Field Name Byte Offset Length name mode uid gid size mtime chksum typeflag linkname magic version uname gname devmajor devminor prefix

0

100

108

116

124

136

148

156

157

257

263

265

297

329

337

345

6

2

32

32

8

8

155

8

8

8

12

12

8

1

100

527186-003 Hewlett-Packard Company 11

35

tar(4)

11

36

OSS System Calls Reference Manual

Symbolic constants used in the header block are defined in the header file /usr/include/tar.h.

The definitions are as follows:

/* ustar and a null */ #define TMAGIC

#define TMAGLEN

#define TVERSION

#define TVERSLEN

"ustar"

6

"00"

2

/* 00 and no null */

/* Values used in typeflag field */

#define REGTYPE ’0’

#define AREGTYPE

#define LNKTYPE

’ ’

’1’

#define SYMTYPE

#define CHRTYPE

#define BLKTYPE

#define DIRTYPE

#define FIFOTYPE

#define CONTTYPE

’2’

’3’

’4’

’5’

’6’

’7’

/* regular file */

/* regular file */

/* line

/* reserved

*/

*/

/* character special */

/* block special */

/* directory */

/* FIFO special */

/* reserved */

/* Bits used in the mode field - values in octal */

#define TSUID 04000 /* set UID on execution */

#define TSGID

#define TSVTX

02000

01000

/* set GID on execution */

/* reserved */

#define TUREAD

#define TUWRITE

#define TUEXEC

#define TGREAD

00400

00200

00100

00040

/* read by owner

/* write by owner

*/

*/

/* execute/search by owner */

/* read by group */

#define TGWRITE

#define TGEXEC

#define TOREAD

#define TOWRITE

#define TOEXEC

00020

00010

00004

00002

00001

/* write by group */

/* execute/search by group */

/* read by other

/* write by other

*/

*/

/* execute/search by other */

The fields in the header block must be contiguous; that is, no padding is used. Each character in the archive file is stored contiguously.

The fields magic, uname, and gname are null-terminated character strings.

The fields name, linkname, and prefix are null-terminated character strings except when all the characters in the field are nonnull characters, including the last character.

The version field is two bytes containing the characters "00" (ASCII zero-zero).

The typeflag field contains a single character.

All other fields are leading zero-filled octal numbers in ASCII. Each numeric field is terminated by one or more space or null characters.

The name and prefix fields produce the pathname of the file. The hierarchical relationship of the file is retained by specifying the pathname as a path prefix, a slash character, and the filename as the suffix. If prefix contains nonnull characters, then the value of prefix, a slash character, and the value of name are concatenated without modification or addition of new characters to produce a new pathname. In this manner, pathnames of at most 256 characters can be supported. If a pathname does not fit in the space provided, the tar command notifies the user of the error and no attempt is made to store any part of the file, header, or data in the archive.

The linkname field does not use prefix to produce a pathname. As such, linkname is limited to

99 characters. If the name does not fit in the space provided, the tar command notifies the user

Hewlett-Packard Company 527186-003

Files tar(4)

of the error and does not attempt to store the link in the archive.

The mode field contains 9 bits specifying file permissions and 3 bits specifying the set user ID

(TSUID), set group ID (TSGID), and unused TSVTX modes. When the user restoring the files from the archive does not have appropriate permission to set these bits, the bits for which the user does not have permission are ignored.

The uid and gid fields are the user and group ID of the file’s owner and group, respectively.

The size field is the size of the file in bytes, as follows:

If the typeflag field specifies a file type of LNKTYPE or SYMTYPE, the size field is 0

(zero).

If the typeflag field specifies a file type of DIRTYPE, the size field is interpreted as described for that record type.

If the typeflag field specifies a file type of CHARTYPE, BLKTYPE, or FIFOTYPE, the meaning of the size field is implementation-defined and no data blocks are stored in the archive.

If the typeflag specifies any other value, the number of blocks written following the header is (value of size + 511)/512, ignoring any fraction in the result of the division.

The mtime field is the modification time of the file at the time it was archived.

The chksum field is the ASCII representation of the octal value of the simple sum of all bytes in the header block. Each 8-bit byte in the header is treated as an unsigned value. These values are added to an unsigned integer that has been initialized to 0 (zero), and that has a precision of no less than 17 bits. When calculating the checksum, the chksum field is treated as if it were all blanks.

The typeflag field specifies the type of file archived. If a particular implementation does not recognize the type, or if the user does not have appropriate privilege to create that type, the file is extracted as if it were a regular file, if possible. If conversion to a regular file occurs, the tar command produces an error message indicating that the conversion took place.

The magic field indicates that the archive was output in tar archive file format. If this field contains the value TMAGIC, the uname and gname fields contain the ASCII representation of the owner and group of the file respectively. When the archive is restored, the password and group files are scanned for these names. If found, the user and group IDs from these files are used instead of the values contained within the uid and gid fields.

RELATED INFORMATION

Commands: pax(1), pinstall(1).

527186-003 Hewlett-Packard Company 11

37

termcap(4) OSS System Calls Reference Manual

NAME

termcap - Describes the terminal capability database

SYNOPSIS

/etc/termcap

DESCRIPTION

The termcap database describes terminals. It is used, for example, by the libtermcap library.

Terminals are described in termcap by giving a set of capabilities that they have and by describing how operations are performed. Padding requirements and initialization sequences are also included in termcap.

Entries in termcap consist of fields separated by colons (:). The first field for each terminal gives the names that are known for the terminal, separated by vertical bar (|) characters. The first name is always two characters long and is used by older systems that store the terminal name as a type in a 16-bit word in a system-wide database. The second name given is the most common abbreviation for the terminal. The last name given should be a long name fully identifying the terminal; all other names given are understood to be synonyms for the terminal name. All names but the first and last should be all lowercase letters and should contain no spaces; the last name can be in uppercase letters and can contain spaces for readability.

Terminal names (except for the last, long entry) should be chosen using the following conventions:

The particular piece of hardware making up the terminal should have a root name chosen: for example, hp2621. This name should not contain dashes.

Modes that the hardware can be in or user preferences should be indicated by appending a - (dash) and an indicator of the mode. Therefore, a DEC VT100 terminal in 132column mode would be vt100-w.

The suffixes in the following table should be used where possible.

Table 11

10. Terminal Name Suffixes

Suffix Meaning Example

-w

-am

Wide mode (more than 80 columns)

vt100-w

With automatic margins (usually default)

vt100-am

-nam

Without automatic margins

-n Number of lines on the screen

vt100-nam aaa-60

-na

-np

-rv

No arrow keys (leave them in local)

Number of pages of memory

Reverse video

concept100-na concept100-4p concept100-rv

Terminal Types Supported

When using TELNET to connect to Open System Services, only the terminal type vt100 is supported. Other terminal types described in this reference page are not supported.

Types of Capabilities

All capabilities have 2-letter name codes, such as cm.

Capabilities in termcap are of three types: bool num

Boolean capabilities, which indicate particular features that the terminal has.

Numeric capabilities, which give the size of the display or the size of other attributes.

11

38 Hewlett-Packard Company 527186-003

Files termcap(4)

str String capabilities, which give character sequences that can be used to perform particular terminal operations.

The following table describes the capabilities used to describe terminals.

Notes to the table:

N Indicates numeric parameter(s).

P Indicates that padding can be specified.

* Indicates that padding can be based on the number of lines affected.

o Indicates that the capability is obsolete. New software should not rely on this capability at all.

Table 11

11. Terminal Capabilities

Name Type cr cs ct cv da dB db

DC dC dc dF

DL dl cd ce ch cl

CM cm co as bc bl bs ae

AL al am bt bw

CC

str str str str bool num bool str num str num str str str str str str str str num str str str bool str str str bool str bool str

Notes Description

(P)

(o)

(P)

(o)

(P)

(P) End alternate character set

(NP*) Add n new blank lines

(P*) Add new blank line

Terminal has automatic margins

Start alternate character set

Backspace if not ˆH

Audible signal (bell)

Terminal can backspace with ˆH

Back tab

The le (backspace) wraps from column 0 to last column

Terminal settable command character in prototype

(P*)

(P)

(NP)

(P*)

(NP)

(NP)

Clear to end of display

Clear to end of line

Set cursor column (horizontal position)

Clear screen and home cursor

Memory-relative cursor addressing

Screen-relative cursor motion

Number of columns in a line (see NOTES section)

(P)

(NP)

(P)

(NP)

Carriage return

Change scrolling region (DEC VT100 terminal)

Clear all tab stops

Set cursor row (vertical position)

(o)

Display can be retained above the screen

Milliseconds of bs delay needed (default 0)

Display can be retained below the screen

(NP*) Delete n characters

(o)

(P*)

Milliseconds of cr delay needed (default 0)

Delete character

(o) Milliseconds of ff delay needed (default 0)

(NP*) Delete n lines

(P*) Delete line

527186-003 Hewlett-Packard Company 11

39

termcap(4) OSS System Calls Reference Manual im in iP ip is hc

HD hd ho hs hu hz i1-i3 ec ed ei eo

EP es ff fs gn

IC ic if dm dN

DO do ds dT dV it

num

kb kC kD kd kE ke kF

K1

K2

K3

K4

K5

str

k0-k9

str

kA ka

str str str str str str str str str str str str str bool bool str str bool str bool str str str str bool bool bool str str bool str str str str num str str str num num str bool str str str

(o)

Enter delete mode

Milliseconds of nl delay needed (default 0)

(NP*) Move cursor down n lines

(o)

Down one line

Disable status line

Milliseconds of horizontal tab delay needed (default 0)

(o)

(NP)

Milliseconds of vertical tab delay needed (default 0)

(o)

(P*)

Erase n characters

End delete mode

End insert mode

Can erase overstrikes with a blank

Even parity

Escape can be used on the status line

Hard-copy terminal page eject

Return from status line

Generic line type (for example, dialup, switch)

(o)

(P)

Hardcopy terminal

Half-duplex

Half-line down (forward 1/2 linefeed)

Home cursor

Has extra status line

Half-line up (reverse 1/2 linefeed)

Cannot print ˜s (Hazeltine)

Terminal initialization strings (unsupported)

(NP*) Insert n blank characters

(P*) Insert character

Name of file containing initialization string

(P*)

Enter insert mode

Insert mode distinguishes nulls

Pathname of program for initialization (unsupported)

Insert pad after character inserted

Terminal initialization string (termcap only)

Tabs initially every n positions

Sent by keypad upper left

Sent by keypad upper right

Sent by keypad center

Sent by keypad lower left

Sent by keypad lower right

Sent by function keys 0 to 9

Sent by insert-line key

Sent by clear-all-tabs key

Sent by backspace key

Sent by clear-screen or erase key

Sent by delete-character key

Sent by down-arrow key

Sent by clear-to-end-of-line key

Out of keypad transmit mode

Sent by scroll-forward/down key

11

40 Hewlett-Packard Company 527186-003

Files termcap(4)

bool str bool str bool bool str str str str str bool str bool str str num str str str str str bool str str str str str str str bool str num str str str str str str str str str str bool str str num

NL nl ns nw

OP os ml mm mo mp mr ms mu nc nd ll lm ma mb md me mh mi mk kH kh kI kL kl kM km kN kn ko kP kR kr kS ks kT kt ku l0-l9

LC

LE le li

(o)

(o)

(o)

(o)

(o)

(P)

(o)

(o)

(o)

(o)

(NP)

(P)

(o)

(o)

Sent by home-down key

Sent by home key

Sent by insert-character or enter-insert-mode key

Sent by delete-line key

Sent by left-arrow key

Sent by insert key while in insert mode

Has a meta key (shift, sets parity bit)

Sent by next-page key

Number of function (k0-k9) keys (default 0)

The termcap entries for other nonfunction keys

Sent by previous-page key

Sent by scroll-backward/up key

Sent by right-arrow key

Sent by clear-to-end-of-screen key

Put terminal in keypad transmit mode

Sent by set-tab key

Sent by clear-tab key

Sent by up-arrow key

Labels on function keys if not "fn"

Lowercase characters only

Move cursor left n positions

Move cursor left one position

Number of lines on screen or page (see NOTES section)

Last line, first column

Lines of memory if > li (0 means varies)

Arrow key map (used by vi version 2 only)

Turn on blinking attribute

Turn on bold (extra bright) attribute

Turn off all attributes

Turn on half-bright attribute

Safe to move while in insert mode

Turn on blank attribute (characters invisible)

Memory lock on above cursor

Turn on meta mode (eighth bit)

Turn off meta mode

Turn on protected attribute

Turn on reverse-video attribute

Safe to move in standout modes

Memory unlock (turn off memory lock)

No correctly working cr (Datamedia 2500, Hazeltine 2000 terminals)

Nondestructive space (cursor right)

The \n is newline, not linefeed

Newline character if not \n

Terminal is a CRT, but does not scroll

Newline (behaves like cr followed by do)

Odd parity

Terminal overstrikes

527186-003 Hewlett-Packard Company 11

41

termcap(4) OSS System Calls Reference Manual ts

UC uc ue ug ul

UP up us vb ve vi vs vt wi ws xb tc te ti sa sc se

SF sf sg rf

RI rp rs so

SR sr st ta pb pc pf pk pl pO po ps pt px r1-r3

str

rc

str str str bool str num str str str str str str bool str str num bool str str str str str str str num str num bool str str str str str str str str str str str str str str str str str num

(N)

(o)

Lowest baud where delays are required

Pad character (default NULL)

Turn off the printer

Program function key n to type string s (unsupported)

Program function key n to execute string s (unsupported)

Turn on the printer for n bytes

Turn on the printer

Print contents of the screen

Has hardware tabs (might need to be set with is)

Program function key n to transmit string s (unsupported)

Reset terminal completely to sane modes (unsupported)

(P) Restore cursor to position of last sc

(NP)

Name of file containing reset codes

Move cursor right n positions

(NP*) Repeat character c n times

Reset terminal completely to sane modes (termcap only)

(NP)

(P)

Define the video attributes

Save cursor position

End standout mode

(NP*) Scroll forward n lines

(P) Scroll text up

Number of garbage characters left by so or se (default 0)

Begin standout mode

(NP*) Scroll backward n lines

(P) Scroll text down

Set a tab in all rows, current column

(P) Tab to next 8-position hardware tab stop

Entry of similar terminal (must be last)

String to end programs that use termcap

String to begin programs that use termcap

(N)

(o)

Go to status line, column n

Uppercase characters only

Underscore one character and move past it

End underscore mode

Number of garbage characters left by us or ue (default 0)

Underline character overstrikes

(NP*) Move cursor up n lines

Up a line (cursor up)

Start underscore mode

Visible bell (must not move cursor)

Make cursor appear normal (undo vs/vi)

(N)

Make cursor invisible

Make cursor very visible

Virtual terminal number (not supported on all systems)

Set current window

Number of columns in status line

Beehive (f1=ESC, f2=ˆC)

11

42 Hewlett-Packard Company 527186-003

Files termcap(4) xn xo xr xs xt xx

bool bool bool bool bool bool

(o)

Newline ignored after 80 columns (Concept)

Terminal uses xoff/xon (DC3/2DC1) handshaking

Return acts like ce cr nl (Delta Data)

Standout not erased by overwriting (Hewlett-Packard terminals)

Tabs ruin magic so character (Teleray 1061 terminal)

Tektronix 4025 terminal insert-line (o)

A Sample Entry

The following entry, which describes the Concept-100, is among the more complex entries in the

termcap file as of this writing: ca | concept100 | c100 | concept | c104 | concept100-4p | HDS Concept-100:\

:al=3*\EˆR:am:bl=ˆG:cd=16*\EˆC:ce=16\EˆU:cl=2*ˆL:cm=\Ea%+ %+ :\

:co#80:.cr=9ˆM:db:dc=16\EˆA:dl=3*\EˆB:do=ˆJ:ei=\E\200:eo:im=\EˆP:in:\

:ip=16*:is=\EU\Ef\E7\E5\E8\El\ENH\EK\E\200\Eo&\200\Eo\47\E:k1=\E5:\

:k2=\E6:k3=\E7:kb=ˆh:kd=\E<:ke=\Ex:kh=\E?:kl=\E>:kr=\E=:ks=\EX:\

:ku=\E;:le=ˆH:li#24:mb=\EC:me=\EN\200:mh=\EE:mi:mk=\EH:mp=\EI:\

:mr=\ED:nd=\E=:pb#9600:rp=0.2*\Er%.%+ :se=\Ed\Ee:sf=ˆJ:so=\EE\ED:\

:.ta=8\t:te=\Ev \200\200\200\200\200\200\Ep\r\n:\

:ti=\EU\Ev 8p\Ep\r:ue=\Eg:ul:up=\E;:us=\EG:\

:vb=\Ek\200\200\200\200\200\200\200\200\200\200\200\200\200\200\EK:\

:ve=\Ew:vs=\EW:vt#8:xn:\

:bs:cr=ˆM:dC#9:dT#8:nl=ˆJ:ta=ˆI:pt:

Entries can continue onto multiple lines by using a \ (backslash) as the last character of a line, and empty fields can be included for readability (here between the last field on a line and the first field on the next). Comments can be included on lines beginning with a # (number sign) character.

For instance, the fact that the Concept terminal has automatic margins (that is, an automatic return and linefeed when the end of a line is reached) is indicated by the Boolean capability am.

Hence the description of the Concept includes am.

In the termcap file, numeric capabilities are followed by the # (number sign) character and the value. In the preceding example, the co capability, which indicates the number of columns in the display, has the value 80 for the Concept terminal.

In the termcap file, string-valued capabilities such as ce (clear-to-end-of-line sequence) are given by the two-letter capability code, an = (equal sign), then a string ending at the next following : (colon).

A delay in milliseconds can appear after the = in such a capability, which causes padding characters to be supplied after the remainder of the string is sent to provide this delay. The delay can be either a number (for example, 20), or a number followed by an * (for example, 3*). An * (asterisk) indicates that the padding required is proportional to the number of lines affected by the operation, and the amount given is the per-affected-line padding required. (In the case of insertcharacter, the factor is still the number of lines affected; this is always a 1 unless the terminal has

in capability and the software uses it.) When an * (asterisk) is specified, it is sometimes useful to give a delay of the form 3.5 to specify a delay per line to tenths of milliseconds. (Only one decimal place is allowed.)

A number of escape sequences are provided in the string-valued capabilities for easy encoding of control characters there. \E maps to an ESC character, ˆX maps to a <Ctrl-X> for any appropriate

X, and the sequences \n, \r, \t, \b, and \f map to linefeed, return, tab, backspace, and formfeed, respectively. Finally, characters can be given as three octal digits after a \ (backslash), and the characters ˆ (circumflex) and \ can be given as and \\. If it is necessary to place a : (colon) in a capability, it must be encoded in octal as \072. If it is necessary to place a NUL character in a

527186-003 Hewlett-Packard Company 11

43

termcap(4) OSS System Calls Reference Manual

string capability, it must be encoded as \200. (The routines that deal with termcap use C strings and strip the high bits off the output very late, so that \200 has the same result as \000.)

In the termcap file, individual capabilities must sometimes be commented out. To do this, put a .

(dot) before the capability name. For example, see the first cr and ta capabilities in the preceding example.

Basic Capabilities

The number of columns on each line of the terminal display is given by the co numeric capability. If the display is a CRT, then the number of lines on the screen is given by the li capability. If the display wraps around to the beginning of the next line when the cursor reaches the right margin, then indicate this with the am capability. If the terminal can clear its screen, indicate this with the cl string capability. If the terminal overstrikes (rather than clearing the position when a character is overwritten), indicate this with the os capability. If the terminal is a printing terminal, with no soft copy unit, indicate this with both the hc and os capabilities. (os applies to storage scope terminals, such as the Tektronix 4010 series, as well as to hard-copy and APL terminals.) If there is a code to move the cursor to the left edge of the current row, indicate this with the cr capability. (Normally this is carriage return, ˆM.) If there is a code to produce an audible signal (bell, beep, and so forth), indicate this with the bl capability.

If there is a code (such as a backspace) to move the cursor one position to the left, indicate this with the le capability. Similarly, codes to move to the right, up, and down should be indicated with the nd, up, and do capabilities, respectively. These local cursor motions should not alter the text they pass over; for example, you would not normally use nd= unless the terminal has the os capability, because the space would erase the character moved over.

Note that the local cursor motions encoded in termcap have undefined behavior at the left and top edges of a CRT display. Applications should never attempt to backspace around the left edge, unless bw is given, and never attempt to go up off the top using local cursor motions.

To scroll text up, an application goes to the bottom left corner of the screen and sends the string given by the sf (index) capability. To scroll text down, an application goes to the top left corner of the screen and sends the string given by the sr (reverse index) capability. The strings given by

sf and sr have undefined behavior when not on their respective corners of the screen. Parameterized versions of the scrolling sequences are the SF and SR capabilities, which have the same semantics as sf and sr except that they take one parameter and scroll that many lines. They also have undefined behavior except at the appropriate corner of the screen.

The am capability indicates whether the cursor sticks at the right edge of the screen when text is output there, but this action does not necessarily apply to the action of the nd capability from the last column. Leftward local motion is defined from the left edge only when the bw capability is given; then the action of the le capability from the left edge moves to the right edge of the previous row. This is useful for drawing a box around the edge of the screen, for example. If the terminal has switch-selectable automatic margins, the termcap description usually assumes that this feature is on (that is, assumes the am capability). If the terminal has a command that moves to the first column of the next line, that command can be given as the nw (newline) capability. It is permissible for this action to clear the remainder of the current line, so if the terminal has no correctly working CR and LF, it is still possible to create a working nw capability out of one or both of them.

These capabilities suffice to describe hard-copy and "glass-tty" terminals. Thus, the Teletype model 33 is described as follows:

T3 | tty33 | 33 | tty | Teletype model 33:\

:bl=ˆG:co#72:cr=ˆM:do=ˆJ:hc:os:

and the Lear Siegler ADM-3 terminal is described as follows:

l3 | adm3 | 3 | LSI

ADM

-3:\

11

44 Hewlett-Packard Company 527186-003

Files termcap(4)

:am:bl=ˆG:cl=ˆZ:co#80:cr=ˆM:do=ˆJ:le=ˆH:li#24:sf=ˆJ:

Parameterized Strings

Cursor addressing and other strings requiring parameters are described by a parameterized string capability, with escape encodings like those of the printf( ) function (%x) in it, while other characters are passed through unchanged. For example, to address the cursor, the cm capability is given, using two parameters: the row and column to move to. Rows and columns are numbered from 0 (zero) and refer to the physical screen visible to the user, not to any unseen memory. If the terminal has memory-relative cursor addressing, that can be indicated by the analogous CM capability.

The % encodings have the following meanings:

%r

%i

%n

%B

%D

%%

%d

%2

%3

%.

%+x

%>xy

Writes %

Writes value as printf( ) %d encoding does

Writes value as printf( ) %2d encoding does

Writes value as printf( ) %3d encoding does

Writes value as printf( ) %c encoding does

Adds x to value, then writes %

If value > x then adds y (no output)

Reverses order of two parameters (no output)

Increments by 1 (one) (no output)

Exclusive ORs all parameters with 0140 (Datamedia 2500)

BCD (16*(value/10)) + (value%10) (no output)

Reverse coding (value - 2*(value%16)) (no output) (Delta Data terminal)

Consider the Hewlett-Packard 2645 terminal, which, to get to row 3 and column 12, needs to be sent \E&a12c03Y padded for 6 milliseconds. Note that the order of the row and column coordinates is reversed here and that the row and column are sent as 2-digit integers. Thus, its cm capability is cm=6\E&%r%2c%2Y.

The Microterm ACT-IV terminal needs the current row and column sent simply encoded in binary preceded by a ˆT, cm=ˆT%.%.. Terminals that use %. need to be able to backspace the cursor (the le capability) and to move the cursor up one line on the screen (the up capability).

This is necessary because it is not always safe to transmit \n, ˆD, and \r, as the system can change or discard them. (Applications using termcap must set terminal modes so that tabs are not expanded, so \t is safe to send. This is essential for the Ann Arbor 4080 terminal.)

A final example is the Lear Siegler ADM-3a terminal, which offsets row and column by a blank character; thus, cm=\E=%+ %+.

Row or column absolute cursor addressing can be given as single-parameter capabilities ch (horizontal position absolute) and cv (vertical position absolute). Sometimes these are shorter than the more general two-parameter sequence (as with the Hewlett-Packard 2645 terminal) and can be used in preference to cm. If there are parameterized local motions (for example, move n positions to the right), these can be given as the DO, LE, RI, and UP capabilities with a single parameter indicating how many positions to move. These capabilities are primarily useful for terminals that do not have the cm capability, such as the Tektronix 4025 terminal.

527186-003 Hewlett-Packard Company 11

45

termcap(4) OSS System Calls Reference Manual

Cursor Motions

If the terminal has a fast way to home the cursor (to the upper left-hand corner of the screen), this can be given as the ho capability. Similarly, a fast way of getting to the lower left-hand corner can be given as the ll capability; this way can involve going up with the up capability from the home position, but an application should never do this itself (unless ll does), because it can make no assumption about the effect of moving up from the home position. Note that the home position is the same as cursor address (0,0): to the top left corner of the screen, not of memory.

Therefore, the \EH sequence on Hewlett-Packard terminals cannot be used for the ho capability.

Area Clears

If the terminal can clear from the current position to the end of the line, leaving the cursor where it is, this should be given as the ce capability. If the terminal can clear from the current position to the end of the display, this should be given as the cd capability. cd must be invoked only from the first column of a line. (Therefore, it can be simulated by a request to delete a large number of lines, if a true cd capability is not available.)

Insert/Delete Line

If the terminal can open a new blank line before the line containing the cursor, this should be given as the al capability; this action must be invoked only from the first position of a line. The cursor must then appear at the left of the newly blank line. If the terminal can delete the line that the cursor is on, this should be given as the dl capability; this action must be used only from the first position on the line to be deleted. Versions of al and dl that take one parameter and insert or delete the indicated number of lines can be given as the AL and DL capabilities.

If the terminal has a settable scrolling region (like the DEC VT100 terminal), the command to set this can be described with the cs capability, which takes two parameters: the top and bottom lines of the scrolling region. The cursor position is, therefore, undefined after using this capability. It is possible to get the effect of insert or delete line using this capability — the sc and rc (save and restore cursor) capabilities are also useful. Inserting lines at the top or bottom of the screen can also be done using the sr or sf capability on many terminals without a true insert/delete line feature, and sr and sf are often faster even on terminals with insert/delete line features.

Terminals with the "magic cookie" glitches (the sg and ug capabilities), rather than maintaining extra attribute bits for each character cell, instead deposit special cookies, or garbage characters, when they receive mode-setting sequences, which affect the display algorithm.

Some terminals, such as the Hewlett-Packard 2621 terminal, automatically leave standout mode when they move to a newline or when the cursor is addressed. Applications using standout mode should exit standout mode on such terminals before moving the cursor or sending a newline. On terminals where this is not a problem, the ms capability should be present to indicate that this overhead is unnecessary.

If the terminal has a way of flashing the screen to indicate an error quietly (a bell replacement), this can be indicated by the vb capability; this action must not move the cursor.

If the cursor needs to be made more visible than normal when it is not on the bottom line (to change, for example, a nonblinking underline into an easier-to-find block or blinking underline), indicate the vs capability. If there is a way to make the cursor completely invisible, indicate the

vi capability. The ve capability, which undoes the effects of both of these modes, should also be specified.

If your terminal correctly displays underlined characters (with no special codes needed), even though it does not overstrike, then you should specify the ul capability. If overstrikes can be erased with a blank, indicate that by specifying the eo capability.

11

46 Hewlett-Packard Company 527186-003

Files termcap(4) kP kF kR kT kS kI kA kN kC kD kL kM kE kH kb ka kt

Keypad Support

If the terminal has a keypad that transmits codes when the keys are pressed, this information can be provided in termcap. Note that it is not possible to handle terminals where the keypad works only in local mode (this applies, for example, to the unshifted Hewlett-Packard 2621 terminal’s keys). If the keypad can be set to transmit or not transmit, specify the ks and ke capabilities.

Otherwise, the keypad is assumed to always transmit. The codes sent by the left-arrow, rightarrow, up-arrow, down-arrow, and home keys can be specified by the kl, kr, ku, kd, and kh capabilities, respectively. If there are function keys such as f0, f1, ..., f9, the codes they send can be specified by the k0, k1,..., k9 capabilities. If these keys have labels other than the default f0 through f9, the labels can be specified by the l0, l1,..., l9 capabilities.

The codes transmitted by certain other special keys can be specified by the following capabilities:

Home down

Backspace

Clear all tabs

Clear the tab stop in this column

Clear screen or erase

Delete character

Delete line

Exit insert mode

Clear to end of line

Clear to end of screen

Insert character or enter insert mode

Insert line

Next page

Previous page

Scroll forward/down

Scroll backward/up

Set a tab stop in this column

In addition, if the keypad has a 3-by-3 array of keys including the four arrow keys, then the other five keys can be specified by the K1, K2, K3, K4, and K5 capabilities. These keys are useful when the effects of a 3-by-3 directional pad are needed. The obsolete ko capability, used to describe "other" function keys, has been completely replaced by the preceding list of capabilities.

The ma capability is also used to indicate arrow keys on terminals that have single-character arrow keys. It is obsolete but still in use in version 2 of the vi utility, which must be run on some minicomputers due to memory limitations. The ma capability is redundant with the kl, kr, ku,

kd, and kh capabilities. The ma capability consists of groups of two characters. In each group, the first character is what an arrow key sends, and the second character is the corresponding vi command. These vi commands are h for the kl capability, j for kd, k for ku, l for kr, and H for

kh. For example, the Microterm Mime terminal would have ma=ˆHhˆKjˆZkˆXl indicating arrow keys left (ˆH), down (ˆK), up (ˆZ), and right (ˆX). (There is no home key on the Microterm Mime

527186-003 Hewlett-Packard Company 11

47

termcap(4) OSS System Calls Reference Manual

terminal.)

Tabs and Initialization

If the terminal needs to be in a special mode when running a program that uses these capabilities, the codes to enter and exit this mode can be specified by the ti and te capabilities. This need arises, for example, from terminals like the Concept terminal with more than one page of memory. If the terminal has only memory-relative cursor addressing and not screen-relative cursor addressing, a screen-sized window must be fixed into the display for cursor addressing to work properly. This is also used for the Tektronix 4025 terminal, where the ti capability sets the command character to be the one used by termcap.

Other capabilities include is, an initialization string for the terminal, and if, the name of a file containing long initialization strings. These strings are expected to set the terminal into modes consistent with the rest of the termcap description. They are printed in the following order:

is

• setting tabs using the ct and st capabilities

if

A pair of sequences that does a harder reset from a totally unknown state can be analogously given as the rs and if capabilities. These strings are output by the reset program, which is used when the terminal gets into a wedged state. Commands are normally placed in the rs and rf capabilities only if they produce annoying effects on the screen and are not necessary when logging in. For example, the command to set the DEC VT100 terminal into 80-column mode would normally be part of the is capability, but it causes annoying behavior of the screen and is not normally needed because the terminal is usually already in 80-column mode.

If the terminal has hardware tabs, the command to advance to the next tab stop can be indicated by the ta capability (usually ˆI). A backtab command that moves leftward to the previous tab stop can be indicated by the bt capability. By convention, if the terminal driver modes indicate that tab stops are being expanded by the computer rather than being sent to the terminal, applications should not use ta or bt, even if they are present, because the user might not have the tab stops properly set. If the terminal has hardware tabs that are initially set every n positions when the terminal is powered up, then the numeric it capability is given, indicating the number of positions between tab stops.

If there are commands to set and clear tab stops, they can be given as the ct (clear all tab stops) capability and the st (set a tab stop in the current column of every row) capability. If a more complex sequence is needed to set the tabs than can be described by this, the sequence can be placed in the is or if capabilities.

Delays

Certain capabilities control padding in the terminal driver. Delays embedded in the capabilities

cr, sf, le, ff, and ta cause the appropriate delay bits to be set in the terminal driver. If the pb capability (padding baud rate) is given, these values can be ignored at baud rates below the value of

pb.

Miscellaneous

If the terminal requires other than a NULL (zero) character as a pad, this can be indicated by the

pc capability. Only the first character of the pc string is used.

If the terminal has commands to save and restore the position of the cursor, indicate this with the

sc and rc capabilities.

If the terminal has an extra status line that is not normally used by software, this fact can be indicated in termcap. If the status line is viewed as an extra line below the bottom line, then the hs capability should be given.

11

48 Hewlett-Packard Company 527186-003

Files termcap(4)

Special strings to go to a position in the status line and to return from the status line can be given as the ts and fs capabilities. (Note that fs must leave the cursor position in the same place that it was before ts. If necessary, the strings from the sc and rc capabilities can be included in ts and

fs to get this effect.) The ts capability takes one parameter, which is the column number of the status line to which the cursor is to be moved.

If escape sequences and other special commands such as tab work while in the status line, the es capability can be given. A string that turns off the status line (or otherwise erases its contents) should be indicated by the ds capability.

The status line is normally assumed to be the same width as the rest of the screen; that is, the value indicated in the co capability. If the status line is a different width (possibly because the terminal does not allow an entire line to be loaded), then its width in columns can be indicated with the numeric ws capability.

If the terminal can move up or down half a line, this can be indicated with the hu (half-line up) and hd (half-line down) capabilities. This feature is primarily useful for superscripts and subscripts on hard-copy terminals. If a hard-copy terminal can eject to the next page (formfeed), indicate this with the ff capability (usually ˆL).

If the terminal has a settable command character, such as the Tektronix 4025 terminal, indicate this with the CC capability. A prototype command character is chosen that is used in all capabilities. This character is given in the CC capability to identify it. The following convention is supported on some UNIX systems: the environment is searched for a CC variable, and if found, all occurrences of the prototype character are replaced by the character in the environment variable. Do not use the CC environment variable in this way; it conflicts with the make command.

Terminal descriptions that do not represent a specific kind of known terminal, such as switch,

dialup, patch, and network, should include the gn (generic) capability so that applications can explain that they do not know how to talk to the terminal. (This capability does not apply to vir-

tual terminal descriptions for which the escape sequences are known.)

If the terminal uses xoff/xon (DC3/DC1) handshaking for flow control, indicate this with the xo capability. Padding information should still be included so that routines can make better decisions about costs, but actual pad characters are not transmitted.

If the terminal has a meta key that acts as a shift key by setting the 8th bit of any character transmitted, then this fact can be indicated with the km capability. Otherwise, software assumes that the 8th bit is parity and it will usually be cleared. If strings exist to turn this meta mode on and off, they can be given by the mm and mo capabilities.

If the terminal has more lines of memory than will fit on the screen at once, the number of lines of memory can be indicated with the lm capability. An explicit value of 0 (zero) indicates that the number of lines is not fixed but there is still more memory than fits on the screen.

If the terminal is one of those supported by the UNIX system virtual terminal protocol, the terminal number can be given by the vt capability.

Media copy strings that control an auxiliary printer connected to the terminal can be given with the following capabilities:

ps pf po

Prints the contents of the screen

Turns off the printer

Turns on the printer

When the printer is on, all text sent to the terminal is sent to the printer. It is undefined whether the text is also displayed on the terminal screen when the printer is on. A variation, the pO capability, takes one parameter and leaves the printer on for as many characters as the value of the parameter, then turns the printer off. The parameter should not exceed 255. All text, including

527186-003 Hewlett-Packard Company 11

49

termcap(4) OSS System Calls Reference Manual

pf, is transparently passed to the printer while pO is in effect.

Similar Terminals

If there are two very similar terminals, one can be defined as being just like the other with certain exceptions. The tc string capability can be given with the name of the similar terminal. This capability must be specified last, and the combined length of the entries must not exceed 1024.

The capabilities given before tc override those in the terminal type invoked by tc.

A capability can be canceled by placing xx@ to the left of the tc invocation, where xx is the capability. For example, the following entry defines a Hewlett-Packard 2621-nl that does not have the ks or ke capabilities, so it does not turn on the function key labels when in visual mode:

hn | 2621-nl:ks@:ke@:tc=2621:

Canceling capabilities can be useful for different modes for a terminal or for different user preferences.

NOTES

This reference page documents obsolete function that is provided only for compatibility.

Lines and columns are now stored by the kernel, as well as in the termcap entry. Most applications now use the kernel information primarily; the information in termcap is used only if the kernel does not have any information.

The total length of a single entry, excluding only escaped newlines, cannot exceed 1024.

Not all applications support all entries.

Hazeltine terminals, which do not allow ˜ (tilde) characters to be displayed, should be assigned the hz capability.

The nc capability, now obsolete, was formerly needed for Datamedia terminals, which echo \r \n for carriage return and then ignore a following linefeed.

Terminals that ignore a linefeed immediately after an am wrap, such as the Concept terminals, should be assigned the xn capability.

If the ce capability is required to get rid of standout (instead of merely writing normal text on top of it), the xs capability should be indicated.

Teleray terminals, where tabs turn all characters moved over to blanks, should be assigned the xt

(destructive tabs) capability. This capability is also taken to mean that it is not possible to position the cursor on top of a "magic cookie," and that to erase standout mode, it is necessary to use delete and insert line.

The Beehive Superbee terminal, which is unable to correctly transmit the ESC or ˆC characters, has the xb capability, indicating that the f1 key is used for ESC and f2 for ˆC. (Only certain

Beehive Superbee terminals have this problem, depending on the ROM.)

Other specific terminal problems can be corrected by adding more capabilities of the form xx.

The names of many of the terminals listed is this reference page are trademarks of the companies that manufacture the terminals.

RELATED INFORMATION

Functions: printf(3).

11

50 Hewlett-Packard Company 527186-003

Files termios(4)

NAME

termios - Describes the terminal interface for POSIX compatibility

SYNOPSIS

#include <termios.h>

DESCRIPTION

The /usr/include/termios.h header file contains information used by system calls that apply to terminal files. The definitions, values, and structure in this file are required for compatibility with the Institute of Electrical and Electronics Engineers (IEEE) P1003.1 Portable Operating System

Interface for Computer Environments (POSIX) standard.

The general terminal interface information is contained in the termios.h header file. The termios structure in the termios.h header file defines the basic input, output, control, and line discipline modes. The termios structure contains the following fields:

c_iflag

Describes the basic terminal input control. The possible input modes are as follows:

BRKINT

ICRNL

IGNBRK

IGNCR

IGNPAR

INLCR

INPCK

ISTRIP

IXANY

IXOFF

Interrupts a signal on the break condition. If set, the break condition generates an interrupt signal and flushes both the input and output queues. This flag is initially set by default.

Maps a CR character to an NL character on input. If set, a received CR character is translated into an NL character. This flag is initially not set by default.

Ignores the break condition. If set, the break condition is not put on the input queue and is therefore not read by any process.

This flag is initially not set by default.

Ignores the CR character. If set, a received CR character is ignored (not read). This flag is initially not set by default.

Ignores bytes with parity errors. Not supported in the current release. This flag is initially not set by default.

Maps newline character (NL) to carriage return (CR) on input. If set, a received NL character is translated into a CR character.

This flag is initially not set by default.

Enables input character byte parity checking. Not supported in the current release. This flag is initially not set by default.

Strips characters. If set, valid input characters are first stripped to 7 bits; if not set, all 8 bits are processed. This flag is initially set by default.

Enables any character to restart output. If set, any character received restarts output. If not set, stopped output is restarted by other conventions. This flag is initially not set by default.

Enables start and stop input control. If set, the system transmits a

STOP character when the input queue is nearly full and a

START character when enough input has been read that the queue is nearly empty again. This flag is initially set by default.

527186-003 Hewlett-Packard Company 11

51

termios(4) c_oflag c_cflag

OSS System Calls Reference Manual

IXON

PARMRK

Enables start and stop output control. If set, a received STOP character suspends output and a received START character restarts output. The START and STOP characters perform flow control functions, but they are not read. This flag is initially set by default.

Marks parity errors. If set, a character with a framing or parity error that is not ignored is read as the 3-character sequence

0377, 0, x, where the x variable is the data of the character received in error. If the ISTRIP mode is not set, then a valid character of 0377 is read as 0377, 0377 to avoid ambiguity. If the PARMRK mode is not set, a framing or parity error that is not ignored is read as the null character. This flag is initially not set by default.

Specifies how the system treats output. The possible output modes are as follows:

OCRNL

ONLCR

ONLRET

ONOCR

Maps CR character to NL character during output. If set, mapping occurs; if not set, mapping does not occur. This flag is initially not set by default.

Maps NL character to CR-NL character sequence during output.

If set, mapping occurs; if not set, mapping does not occur. This flag is initially set by default.

If set, the NL character performs the CR character function. If not set, the NL character does not perform the CR character function. This flag is initially not set by default.

If set, no CR character is sent for the column 0 (zero) position.

If not set, the CR character is sent for the column 0 (zero) position. This flag is initially not set by default.

OPOST

If set, the remaining flag masks are interpreted as described; otherwise, characters are transmitted without change. This flag is initially set by default.

Setting ONLRET or ONLCR causes a terminal emulator to return the error

[EINVAL] for the tcsetattr( ) function call, so these flags are effectively not supported.

Describes the hardware control of the terminal. In addition to the basic control modes, this field uses the following control characters:

CLOCAL

CREAD

CSIZE

Specifies a local line. If set, the line is assumed to have a local, direct connection with no modem control. If not set, modem control (dialup) is assumed.

Enables receiver. If set, the receiver is enabled. If not set, characters are not received.

Specifies the number of bits per character byte. The values of

CS7 and CS8 are recognized. The values of CS5 and CS6 are ignored.

11

52 Hewlett-Packard Company 527186-003

Files c_lflag

527186-003

termios(4)

CSTOPB

CS5

CS6

CS7

CS8

HUPCL

PARENB

PARODD

Specifies the number of stop bits. If set, two stop bits are sent; if not set, only one stop bit is sent. Higher baud rates require two stop bits. (At 110 baud, for example, 2 stop bits are required.)

Specifies a data byte of 5 bits. This value is ignored in the current release.

Specifies a data byte of 6 bits. This value is ignored in the current release.

Specifies a data byte of 7 bits.

Specifies a data byte of 8 bits.

Hangs up on last close. If set, the line is disconnected when the last process closes the line or when the process terminates (when the "data terminal ready" signal drops).

Enable parity detection. Not supported in the current release.

Specifies odd parity if set or even parity if not set. Not supported in the current release.

The initial hardware control value after an open is CS8, CREAD, and HUPCL.

Controls various terminal functions. The initial value after an open is all bits clear. In addition to the basic modes, this field uses the following mask name symbols:

ECHO

ECHOE

ECHOK

ECHONL

ICANON

Enables echo. If set, characters are displayed on the terminal screen as they are received.

Echoes erase character as BS-SP-BS. If ECHOE is set but

ECHO is not set, the erase character is implemented as ASCII

SP-BS.

Echoes NL after kill.

Echoes NL. If ECHONL is set, the line is cleared when a newline function is performed whether or not ECHO is set. This is useful for terminals that are set to local echo (also referred to as half-duplex). Unless an escape character precedes an EOF, the

EOF character is not displayed. Because the ASCII EOT character is the default End-of-File character, this prevents terminals that respond to the EOT character from hanging up.

Enables canonical input. If set, canonical processing is enabled, which enables the erase and kill edit functions as well as the assembly of input characters into lines delimited by NL, EOF, and EOL.

If ICANON is not set, read requests are satisfied directly from the input queue. In this case, a read request is not satisfied until one of the following conditions is met: either the minimum number of characters specified by MIN are received, or the time-out value specified by TIME has expired since the last character was received. This allows bursts of input to be read, while still allowing single-character input. The MIN and TIME values are stored in the positions for the EOF and EOL

Hewlett-Packard Company 11

53

termios(4) c_cc

OSS System Calls Reference Manual

IEXTEN

ISIG

NOFLSH

TOSTOP

characters, respectively. The time value represents tenths of a second.

Enable extended (implementation-defined) functions. Not supported in the current release.

Enables signals. If set, each input character is checked against the INTR and QUIT special control characters. If a character matches one of these control characters, the function associated with that character is performed. If ISIG is not set, checking is not done.

Disables queue flushing. If set, the normal flushing of the input and output queues associated with the quit and interrupt characters is not done.

Sends a SIGTTOU signal when a process in a background process group tries to write to its controlling terminal. The

SIGTTOU signal stops the members of the process group. If job control is not supported, this symbol is ignored.

The ICANON, ECHO, ECHOE, ECHOK, ECHONL, and NOFLSH special input functions are possible only if ISIG is set. These functions can be disabled individually by changing the value of the control character to an unlikely or impossible value (for example, 0377 octal or 0xFF).

Specifies an array that defines the special control characters. The relative positions and initial values for each function are as follows:

VEOF

VEOL

VERASE

VINTR

VKILL

Indexes the EOF control character (<Ctrl-d>), which can be used at the terminal to generate an End-of-File character. When this character is received, all characters waiting to be read are immediately passed to the program without waiting for a newline, and the EOF is discarded. If the EOF is at the beginning of a line (no characters are waiting), zero characters are passed back, which is the standard End-of-File character.

Indexes the EOL control character (<Ctrl-@> or ASCII null), which is an additional line delimiter that is not normally used.

Indexes the ERASE control character (<Backspace>), which erases the preceding character. The ERASE character does not erase beyond the beginning of the line (delimited by an NL,

EOL, EOF, or EOL2 character).

Indexes the INTR control character (<Ctrl-Backspace>), which sends a SIGINT signal to stop all processes controlled by this terminal.

Indexes the KILL control character (<Ctrl-u>), which deletes the entire line (delimited by an NL, EOL, EOF, or EOL2 character).

11

54 Hewlett-Packard Company 527186-003

Files termios(4)

VSTART

VSTOP

VSUSP

VQUIT

Indexes the START control character (<Ctrl-q>), which resumes output that has been suspended by a STOP character.

START characters are ignored if the output is not suspended.

Indexes the STOP control character (<Ctrl-s>), which can be used to temporarily suspend output. This character is recognized during both input and output if IXOFF (input control) or IXON

(output control) is set.

Indexes the SUSP control character (<Ctrl-z>), which causes a

SIGTSTP signal to be sent to all foreground processes controlled by this terminal. This character is recognized during input if ISIG is set. If job control is not supported, this character is ignored.

Indexes the QUIT control character (<Ctrl-v> or <Ctrl-|>), which sends a SIGQUIT signal to stop all processes controlled by this terminal and writes a saveabend file into the current working directory.

The following values for the optional_actions parameter of the tcsetattr( ) function are also defined in the termios.h header file:

TCSADRAIN Waits until all output written to the object file has been transmitted before setting the terminal parameters from the termios structure.

TCSAFLUSH Waits until all output written to the object file has been transmitted and all input received but not read has been discarded before setting the terminal parameters from the termios structure.

TCSANOW

Immediately sets the parameters associated with the terminal from the referenced

termios structure.

The following values for the queue_selector parameter of the tcflush( ) function are also defined in the termios.h header file:

TCIFLUSH

Flushes data that is received but not read.

TCIOFLUSH Flushes both data that is received but not read and data that is written but not transmitted.

TCOFLUSH

Flushes data that is written but not transmitted.

The following values for the action parameter of the tcflow( ) function are also defined in the

termios.h header file:

TCIOFF

TCION

TCOOFF

TCOON

Transmits a STOP character to stop data transmission by the terminal device.

Transmits a START character to start or restart data transmission by the terminal device.

Suspends the output of data by the object file named in the tcflow( ) function.

Restarts the output of data that was suspended by the TCOOFF value.

527186-003 Hewlett-Packard Company 11

55

termios(4) OSS System Calls Reference Manual

RELATED INFORMATION

Commands: sh(1).

Functions: tcflow(3), tcflush(3), tcsetattr(3).

STANDARDS CONFORMANCE

The HP implementation does not support the following symbolic values for the c_oflag field in the XPG4 Version 2 specification:

BSDLY, CRDLY, FFDLY, NLDLY, OFILL, TABDLY, and VTDLY.

11

56 Hewlett-Packard Company 527186-003

Files tty(7)

NAME

tty - Is the general terminal interface

SYNOPSIS

#include <termios.h>

DESCRIPTION

The tty interface is the general interface for terminal devices. This interface supplies all the functions needed for I/O over console serial lines, workstation screens, keyboards, and other terminal devices. It consists of the special file /dev/tty and terminal drivers used for conversational computing.

Much of a terminal interface’s performance is governed by the settings in the terminal’s termios structure, which is defined in the termios.h header file. This structure provides definitions for terminal input and output processing, control and local modes, and so on.

The Controlling Terminal

Open System Services supports the concept of a controlling terminal. Any process in the system can have a controlling terminal associated with it. Certain events, such as the delivery of keyboard-generated signals (for example, interrupt, quit, and suspend), affect all the processes in the process group associated with the controlling terminal. The controlling terminal also determines the physical device that is accessed when the indirect device /dev/tty is opened.

In Open System Services, in accordance with the POSIX 1003.1 specification, a process must be a session leader to allocate a controlling terminal. (This implies that the O_NOCTTY flag to the

open( ) function must be cleared.) The following code example illustrates the correct sequence for obtaining a controlling tty (no error checking is shown). This code fragment calls the set-

sid( ) function to make the current process the group and session leader and to remove any controlling tty that the process might already have. The code then opens a terminal and attaches it to the current session as the controlling terminal. Note that the process must not already be a session or process group leader and that the console must not already be the controlling tty of any other session.

(void)setsid(); /* become session leader and */

/* lose controlling tty */ fd = open("/G/ZTNT/#PTY5", O_RDWR);

When a controlling terminal file is closed, pending input is removed and pending output is sent to the receiving device.

When a terminal file is opened, the process blocks until a carrier signal is detected. If the open( ) function is called with the O_NONBLOCK flag set, however, the process does not wait.

Instead, the first read( ) or write( ) function call waits for a carrier to be established. If the CLO-

CAL mode is set in the termios structure, the driver assumes that modem control is not in effect and so the open( ), read( ), and write( ) calls proceed without waiting for a carrier signal to be established.

Process Groups

Each OSS process belongs to a process group with a specific process group ID. Each OSS process belongs to the process group of its creating process. This enables related processes to be signaled. Process group IDs are unique identifiers that cannot be used for other system process groups until the original process group is disbanded. Each process group also has a process group leader. A process group leader has the same process ID as its process group.

Each process group belongs to a session. Each process in the process group also belongs to the process group’s session. A process that is not the process group leader can create its own session and process group with a call to the setsid( ) function. That calling process then becomes the session leader of the new session and of the new process group. The new session has no controlling terminal until the session leader assigns one to it. The calling process’s ID is assigned to the new

527186-003 Hewlett-Packard Company 11

57

tty(7) OSS System Calls Reference Manual

process group. With the setpgid( ) function, other processes can be added to a process group.

A controlling terminal can have a process group associated with it that is known as the foreground process group. The terminal’s foreground process group is the one that receives signals generated by the VINTR, VQUIT, and VSUSP special control characters. Certain operations on the terminal are also restricted to processes in the terminal’s foreground process group (see Ter-

minal Access Control, later in this reference page). A terminal’s foreground process group can be changed by calling the tcsetpgrp() function. A terminal’s current foreground process group can be obtained by calling the tcgetpgrp() function.

Input Processing Modes

The terminal drivers have two major modes, characterized by the kind of processing that takes place on the input characters:

Canonical

If a terminal is in canonical mode, input is collected and processed one line at a time. Lines are terminated by a newline (\*L0), End-of-File (VEOF), or Endof-Line (EOL) character. A read request is not returned until either the line is terminated or a signal is received. The maximum number of bytes of unread input allowed on an input terminal is 255 bytes.

Erase and kill processing is performed on input that was not terminated by one of the line-termination characters. Erase processing removes the last character in the line; kill processing removes the whole line.

Noncanonical Noncanonical mode eliminates erase and kill processing, making input characters available to the user program as they are typed. Input is not processed into lines. The received bytes are processed according to the VMIN and VTIME elements of the c_cc array in the termios structure.

VMIN

VTIME

The minimum number of bytes the terminal can receive in noncanonical mode before a read is considered successful.

Measured in 0.1-second units, times out sporadic input.

These cases are summarized as follows:

VMIN>0, VTIME>0

In this case, VTIME is an interbyte timer that is activated after the first byte of the input line is received and reset after each byte is received. The read operation is a success if VMIN bytes are read before VTIME runs out. If VTIME runs out before

VMIN bytes are received, the characters that were received are returned.

VMIN>0, VTIME=0

In this case, only VMIN is used. A queued read( ) function call waits until either VMIN bytes are received or a signal is received.

VMIN=0, VTIME>0

In this case, VTIME is used as a read timer that starts when a

read( ) function call is made. The read( ) call is finished either when one byte is read or when VTIME runs out.

11

58 Hewlett-Packard Company 527186-003

Files tty(7)

VMIN=0, VTIME=0

In this case, either the number of requested bytes or the number of currently available bytes is returned, depending on which is less. The read( ) function call returns 0 (zero) if no data was read.

Canonical mode is entered by setting the ICANON flag of the c_lflag field in the terminal’s ter-

mios structure. Other input processing is performed according to the other flags set in the c_iflag and c_lflag fields.

Input Editing

A terminal ordinarily operates in full-duplex mode. Characters can be typed at any time, even while output is occurring. Characters are lost only when the system’s character input buffers become completely overrun, which is rare, or when the user has accumulated the maximum allowed number of input characters (MAX_INPUT/2) that have not yet been read by some program. Currently this limit is 255 characters.

Input characters are normally accepted in either even or odd parity with the parity bit being stripped off before the character is given to the program. The ISTRIP mask of the c_iflag field controls whether the parity bit is stripped (ISTRIP set) or not stripped (ISTRIP not set). By setting the PARENB flag in the c_cflag field and either setting (or not setting) the PARODD flag, it is possible to have input characters with even or odd parity discarded or marked (see Input

Modes, later in this reference page).

Input characters are normally echoed by putting them in an output queue as they arrive. This can be disabled by clearing the ECHO bit in the c_lflag word using the tcsetattr( ) function.

In canonical mode, terminal input is processed in units of lines. A program attempting to read is normally suspended until an entire line is received (however, see the description of the

SIGTTIN signal under Terminal Access Control, later in this reference page). No matter how many characters are requested in the read call, at most one line is returned. It is not, however, necessary to read a whole line at once; any number of characters can be requested in a read, even one, without losing information. In read( ) requests, the O_NONBLOCK flag affects the read operation.

If the O_NONBLOCK flag is not set, a read( ) request is blocked until either data or a signal is received. If the O_NONBLOCK flag is set, the read( ) request is not blocked and one of the following situations occurs:

Some data might have been typed, but there might or might not be enough data to satisfy the entire read( ) request. In either case, the read( ) function returns the data available, returning the number of bytes of data it read.

If there is no data for the read operation, the read( ) function returns the value -1 with an error value of [EAGAIN].

During input, line editing is normally done with the erase special control character (VERASE) logically erasing the last character typed and the kill special control character (VKILL) logically erasing the entire current input line. These characters never erase beyond the beginning of the current input line or an End-of-File (VEOF) character. These characters, along with the other special control characters, can be entered literally by preceding them with the literal-next character (VLNEXT, for which the default value is <ˆV>).

The drivers normally treat either a newline character (\ n), End-of-File character (VEOF), or

End-of-Line character (VEOL) as terminating an input line, echoing a return and a linefeed. If the ICRNL mode is set in the c_iflag word of the termios structure, then carriage returns are translated to newline characters on input and are normally echoed as carriage return-linefeed sequences. If ICRNL is not set, this processing for carriage return is disabled; it is simply

527186-003 Hewlett-Packard Company 11

59

tty(7) OSS System Calls Reference Manual

echoed as a return and does not terminate canonical mode input.

Input Modes

The termios structure has an input mode field c_iflag, which controls basic terminal input characteristics. These characteristics are masks that can be bitwise inclusive ORed. The masks include:

BRKINT

ICRNL

IGNBRK

IGNCR

INLCR

ISTRIP

IXOFF

IXON

PARMRK

An interrupt is signaled on a break condition.

All carriage returns are mapped to newline characters when input.

Break conditions are ignored.

Carriage returns are ignored.

Newline characters are mapped to carriage returns when they are input.

The 8th bit (parity bit) is stripped on input characters.

STOP and START characters are sent to enable input flow control.

STOP and START characters are recognized for output flow control.

Parity errors are marked with a 3-character sequence.

The input mode mask bits can be combined for the following results.

If IGNBRK is set, input break conditions are ignored. If IGNBRK is not set but

BRKINT is set, the break condition has the same effect as if the VINTR control character had been typed; that is, a SIGINT signal is generated. If neither IGNBRK nor

BRKINT are set, then the break condition is input as a single character 0x00 (zero). If the PARMRK flag is also set, then the input is read as three characters, 0xff, 0x00, and

0x00.

If PARMRK is set, a byte with a parity or framing error, except for breaks, is passed as the three characters 0xff, 0x00, and X, where X is the character data received in error. If

ISTRIP is not set, the valid character 0xff is passed as 0xff, 0xff. If PARMRK is not set, framing or parity errors, including breaks, are passed as the single character 0x00.

Setting ISTRIP causes the 8th bit of the 8 valid input bits to be stripped before processing. If ISTRIP is not set, all 8 bits are processed.

Setting INLCR causes a newline character to be read as a carriage return character. If

IGNCR is also set, the carriage return is ignored. If IGNCR is not set, INLCR works as described earlier in Input Modes.

The STOP character (normally <Ctrl-S>) suspends output, and the START character

(normally <Ctrl-Q>) restarts output. Setting IXON enables stop/start output control, in which the START and STOP characters are not read but rather perform flow control functions. Extra STOP characters typed when output is already stopped have no effect, unless the START and STOP characters are made the same, in which case output resumes. If IXON is not set, the START and STOP characters are read.

If IXOFF is set, stop/start input control is enabled. When IXOFF is set, the terminal device is sent STOP characters to halt the transmission of data when the input queue is in danger of overflowing (exceeds the size MAX_INPUT/2). When enough characters are read to reduce the amount of data queued to an acceptable level, a START character is sent to the device to allow it to continue transmitting data. This mode is useful when the terminal is actually another machine that obeys these conventions.

11

60 Hewlett-Packard Company 527186-003

Files tty(7)

Input Echoing and Redisplay

The terminal driver has several modes for handling the echoing of terminal input, controlled by bits in the c_lflag field of the termios structure.

Erasing Characters From a CRT

When a CRT terminal is in use, the ECHOE bit of the c_lflag field of the termios structure can be set to cause input to be erased from the screen with a backspace-space-backspace sequence when character-deleting or word-deleting sequences are used.

Output Processing

When one or more characters are written, they are actually transmitted to the terminal as soon as previously written characters have finished typing. Input characters are normally echoed by putting them in the output queue as they arrive. When a process produces characters more rapidly than the terminal can accept them, it is suspended when its output queue exceeds some limit.

When the queue has come down to some threshold, the program resumes.

Line Control and Breaks

The tcsendbreak( ) function can cause a break condition for a specified amount of time. Break conditions in the input are handled according to the value in the c_iflag field of the termios structure. (Refer to Input Modes, earlier, for a complete list of the c_iflag field settings.)

When a TELNET disconnect is detected, all OSS open file descriptors are cleared if the terminal window is a dynamic window or a static window with CLOCAL not set in the c_cflag field of the termios structure. All outstanding write requests fail with the error [EIO]. All outstanding read requests return zero bytes read. If CLOCAL is set on a static window, outstanding read and write requests are queued until a new TELNET connection is established. If CLOCAL is not set and a static window is a controlling terminal, a SIGHUP signal is sent to the window’s controlling process.

Interrupt Characters

When ISIG is set in the c_lflag word of termios, there are several characters that generate signals in both canonical and noncanonical mode; all are sent to the processes in the foreground process group of the terminal. If NOFLSH is not set in c_lflag, these characters also flush pending input and output when typed at a terminal. The characters shown here are the default characters; the symbolic names of the indexes of these characters in the c_cc array of termios are also shown. The characters are as follows:

^C

^\

^Z

VINTR (in c_cc) generates a SIGINT signal. This is the normal way to stop a process or to regain control in an interactive program.

VQUIT (in c_cc) generates a SIGQUIT signal. This causes a program to terminate and produce a saveabend file, if possible, in the current directory.

VSUSP (in c_cc) generates a SIGTSTP signal, which is used to suspend the current process group.

Terminal Access Control

If a process attempts to read from its controlling terminal when the process is not in the foreground process group of the terminal, that background process group is sent a SIGTTIN signal, the read returns a -1, and errno is set to [EINTR]. This signal normally causes the members of that process group to stop. If, however, the process is ignoring SIGTTIN or has SIGTTIN blocked, or if the reading process’s process group is orphaned, the read returns the value -1 with

errno set to [EIO] and does not send a signal.

If a process attempts to write to its controlling terminal when the process is not in the foreground process group of the terminal, and if TOSTOP is set in the c_lflag word of the termios structure, the background process group is sent a SIGTTOU signal and the process is prohibited from writing. If TOSTOP is not set, or if TOSTOP is set and the process is blocking or ignoring the

527186-003 Hewlett-Packard Company 11

61

tty(7) OSS System Calls Reference Manual

SIGTTOU signal, the writes to the terminal are allowed and the SIGTTOU signal is not sent. If

TOSTOP is set, if the writing process’s process group is orphaned, and if SIGTTOU is not blocked by the writing process, the write operation returns the value -1 with errno set to [EIO] and does not a send a signal.

The tty Parameters

In contrast to earlier versions of the tty driver, the OSS terminal parameters and structures are contained in a single structure, which is the termios structure defined in the termios.h file.

Basic System Calls

A large number of system calls apply to terminals. The applicable calls follow:

tcgetattr( )

Gets the termios structure and all of its associated parameters. The interface delays until output is quiescent, then throws away any unread characters.

tcsetattr(TCSANOW)

Immediately sets the parameters according to the termios structure.

tcsetattr(TCSADRAIN)

Waits until all output is transmitted and input is read before setting the parameters according to the termios structure.

tcsetattr(TCSAFLUSH)

Waits until all output is transmitted before setting the parameters according to the termios structure. Discards all unread input before setting the parameters.

tcflush( )

Flushes unread input data, nontransmitted output data, or both.

The following system calls perform miscellaneous functions on the controlling terminal. In cases where arguments are required, they are described as a parameter named arg. Otherwise, arg should be specified as the value 0 (zero).

tcflow(TCIOFF)

Output is stopped as if the STOP character were typed.

tcflow(TCION)

Output is restarted as if the START character were typed.

tcflow(TCOOFF)

Output is suspended.

tcflow(TCOON)

Suspended output is restarted.

tcgetpgrp( )

The arg parameter is a pointer to an int parameter into which is placed the process group ID of the process group for which this terminal is the control terminal.

tcsetpgrp( )

The arg parameter is a pointer to an int parameter containing the value to which the process group ID for this terminal will be set.

FILES

/dev/tty

Special file for a tty device.

11

62 Hewlett-Packard Company 527186-003

Files

RELATED INFORMATION

Functions: tcdrain(3), tcflush(3), tcgetattr(3), tcgetpgrp(3), tcsendbreak(3), tcsetattr(3),

tcsetpgrp(3).

Commands: sh(1).

Files: termios(4).

tty(7)

527186-003 Hewlett-Packard Company 11

63

Section 12. Miscellaneous

This section contains reference pages for some miscellaneous Open System Services

(OSS) topics. These reference pages reside in the cat5 directory and are sorted alphabetically by U.S. English conventions in this section.

527186-003 Hewlett-Packard Company 12

1

ascii(5) OSS System Calls Reference Manual

NAME

ascii - Describes the octal, hexadecimal, and decimal ASCII character sets

DESCRIPTION

The octal character set is as follows:

Table 12

1. ASCII Character Set Octal Values

000 nul 001 soh 002 stx 003 etx 004 eot 005 enq 006 ack

007 bel 010 bs 011 ht 012 nl 013 vt 014 np 015 cr

016 so 017 si 020 dle 021 dc1 022 dc2 023 dc3 024 dc4

025 nak 026 syn 027 etb 030 can 031 em 032 sub 033 esc

034 fs 035 gs 036 rs 037 us 040 sp 041 !

042 "

043 # 044 $ 045 % 046 & 047 ’ 050 ( 051 )

052 * 053 + 054 , 055 056 .

057 / 060 0

061 1 062 2 063 3 064 4 065 5 066 6 067 7

070 8 071 9 072 : 073 ; 074 < 075 = 076 >

077 ?

100 @ 101 A 102 B 103 C 104 D 105 E

106 F 107 G 110 H 111 I 112 J 113 K 114 L

115 M 116 N 117 O 120 P 121 Q 122 R 123 S

124 T 125 U 126 V 127 W 130 X 131 Y 132 Z

133 [ 134 \ 135 ] 136 ˆ 137 _ 140 ‘ 141 a

142 b 143 c 144 d 145 e 146 f 147 g 150 h

151 i 152 j 153 k 154 l 155 m 156 n 157 o

160 p 161 q 162 r 163 s 164 t 165 u 166 v

167 w 170 x 171 y 172 z 173 { 174 | 175 }

176 ˜ 177 del

The hexadecimal character set is as follows:

Table 12

2. ASCII Character Set Hexadecimal Values

00 nul 01 soh 02 stx 03 etx 04 eot 05 enq 06 ack

07 bel 08 bs 09 ht 0a nl 0b vt 0c np 0d cr

0e so 0f si 10 dle 11 dc1 12 dc2 13 dc3 14 dc4

15 nak 16 syn 17 etb 18 can 19 em 1a sub 1b esc

1c fs

23 #

2a *

31 1

1d gs

24

2b

32

$

+

2

1e rs

25

2c

33

%

,

3

1f us

26

2d

34

&

-

4

20 sp

27

2e

35

.

5

21

28

2f

36

!

(

/

6

22

29

30

37

"

)

0

7

3f ?

3e >

46 F

4d M

54 T

5b [

62 b

69 i

70 p

77 w

7e ˜

38 8

40 @

47 G

4e N

71

78 q x

7f del

39 9

41 A

48 H

4f O

55 U 56 V

5c \ 5d ]

63 c

6a j

64

6b d k

72 r

79 y

3a

42

49

50

57

5e

65

6c

73

7a

:

B

I

P

W

ˆ e l s z

3b

43

4a

51

58

5f

66

6d

74

7b

;

C

J

Q

X

_ f m t

{

3c

44

4b

52

59

60

67

6e

75

7c

<

D

K

R

Y

` g n u

|

3d =

45 E

4c L

53 S

5a Z

61 a

68 h

6f o

76 v

7d }

12

2 Hewlett-Packard Company 527186-003

Miscellaneous

The decimal character set is as follows:

Table 12

3. ASCII Character Set Decimal Values

0 nul

7 bel

1 soh

8 bs

2 stx

9 ht

3 etx

10 nl

4 eot

11 vt

14 so 15 si 16 dle 17 dc1 18 dc2

21 nak 22 syn 23 etb 24 can 25 em

28 fs

35 #

42 *

49 1

29 gs

36

43

50

$

+

2

30 rs

37

44

51

%

,

3

31 us

38

45

52

&

-

4

32 sp

39

46

53

.

5

56 8

63 ?

70 F

77 M

57 9

64 @

71 G

78 N

58 :

65 A

72 H

79 O

59 ;

66 B

73 I

80 P

60 <

67 C

74 J

81 Q

84 T

91 [

85 U 86 V

92 \ 93 ]

87 W

94 ˆ

88 X

95 _

98 b 99 c 100 d 101 e 102 f

105 i 106 j 107 k 108 l 109 m

112 p 113 q 114 r 115 s 116 t

119 w 120 x 121 y 122 z 123 {

126 ˜ 127 del

5 enq

12 np

6 ack

13 cr

19 dc3 20 dc4

26 sub 27 esc

33 !

40 (

47 /

54 6

34

41

48

55

"

)

0

7

61 =

68 D

75 K

82 R

62 >

69 E

76 L

83 S

89 Y

96 ‘

90 Z

97 a

103 g 104 h

110 n 111 o

117 u 118 v

124 | 125 }

ascii(5)

527186-003 Hewlett-Packard Company 12

3

environ(5) OSS System Calls Reference Manual

NAME

environ - Contains the user environment

SYNOPSIS extern char **environ;

DESCRIPTION

An array of strings called the environment is made available by the execl( ), execle( ), execlp( ),

execv( ), execve( ), execvp( ), tdm_execve( ), or tdm_execvep( ) function when a process begins.

The same array is optionally made available by the tdm_spawn( ) or tdm_spawnp( ) function when a process begins.

COBOL programs also have access to the environment when the COBOL SAVE ALL directive is used at compile time and the Guardian PARAM SAVE-ENVIRONMENT ON is used before starting an OSS shell to run the program.

By convention, these strings have the form name=value. The names used by various commands and utilities are:

AS1

CCOMBE

Specifies the pathname of the C or C++ compiler component used when binary assembly-code conversion to object code is requested. By default, the program

as1 in the directory /usr/lib is used. This environment variable is used for

TNS/R-targeted compilations only.

Determines the pathname of the ccombe component of the C and C++ compilers. | /usr/cmplr/ccombe is the default location for the OSS environment. |

This environment variable is used for TNS/E-targeted compilations only.

CACHE_CDS_SERVER

Specifies the name of the CDS server to cache. The cached server is not required to be the initial CDS server. Used during CDS client configuration by the

dce_config command.

CACHE_CDS_SERVER_IP

Specifies the IP address of the CDS server to cache; used by the dce_config command.

CDPATH

Specifies the search path used for the cd command.

CDS_ADVERTISEMENTS

Controls the behavior of the CDS advertiser. When this variable has the value n, the CDS advertiser is started with the -s switch by the dce_config command, meaning the server does not send or receive advertisements.

The default is y.

CDSD_DATABASE_DIR

Specifies the location of the CDS database files, which is a Guardian subvolume holding NonStop SQL/MP tables. This value is a Guardian subvolume name, expressed in OSS pathname format and surrounded by quotation marks; for example, "/G/volume/subvol".

Used by the dce_config command.

CELL_ADMIN

Specifies the principal name of the initial privileged user of the registry database

(known as the "registry creator"). Used by the dce_config command during security server configuration.

12

4 Hewlett-Packard Company 527186-003

Miscellaneous environ(5)

CELL_ADMIN_PW

Specifies the default password assigned to the accounts created when the registry database is created, including the account for the registry creator. Used by the

dce_config command.

The default is -dce-.

CELL_NAME

Specifies the name of the cell (without the /.../) on which the configuration is being performed. Used during security server configuration by the dce_config command.

CFE

Specifies the pathname of the C or C++ compiler used when C or C++ source statements are present. By default, the program cfe in the directory /usr/lib is used.

This environment variable is used for TNS/R-targeted compilations only.

check_time

Specifies whether to check client and server clock synchronization. (All lowercase characters is correct.)

Valid values are:

y

Indicates time is checked

n

Indicates time is not checked

The default is y.

Used by the dce_config command.

CLONE_FROM

Specifies the name of the virtual host to be used when cloning is performed.

Used by the dce_config command.

This variable is ignored unless CLONING_REQUIRED is set to y. If

CLONING_REQUIRED is set to y, CLONE_FROM must specify the name of a virtual host that is already installed.

CLONING_REQUIRED

Specifies whether binary files of another virtual host should be shared (cloned).

Used by the dce_config command.

Valid values are:

y

Indicates that cloning should occur

n

The default is n.

Indicates that cloning should not occur

COMP_ROOT

Specifies a pathname prefix to be used to find the components of the c89 utility.

COPY_CONFIG_HOST

Specifies the name of the virtual host to be used when copying for replica servers is performed. Used by the dce_config command.

This variable is ignored unless COPY_CONFIG_INFO is set to y. If

COPY_CONFIG_INFO is set to y, then COPY_CONFIG_HOST must specify the name of a virtual host that is already installed.

527186-003 Hewlett-Packard Company 12

5

environ(5) OSS System Calls Reference Manual

12

6

COPY_CONFIG_INFO

Specifies whether the configuration should be copied from another virtual host.

Used by the dce_config command.

Copying implies that an additional CDS or security server is being configured to be a replica of the virtual host named by the COPY_CONFIG_HOST environment variable.

Valid values are:

y

Indicates that copying should occur

n

The default is n.

Indicates that copying should not occur

CPU_LIST

Specifies the processors to be used by the virtual host being configured. Used by the dce_config command.

Processor numbers must be separated by one or more spaces, and the list of numbers must be enclosed in quotation marks. If a specified processor is down or not available, the system allocates a replacement processor.

CRON_NAMED

Specifies the process name to be used when the cron utility is run.

Valid values must conform to Guardian process name rules, cannot begin with a

Z, and must be specified in OSS pathname form (/G/process_name) without the

$ character.

DATEMSK

Specifies the full pathname for the file of date templates used with the getdate( ) function.

DCE_PRIVUSER

Specifies the NonStop operating system user ID permitted to perform privileged operations, such as configuring servers using dce_config. This user ID must be a member of the super group.

The default is the super ID (255,255 with a scalar view of 65535).

DCE_PROCESS_PREFIX

Specifies one alphabetic character to be used as the prefix for virtual host process names. All processes started for a virtual host use this prefix.

The default is Z.

For example, DCE processes started when the default value is used have the

Guardian process names $ZDCED, $ZSECD, and so forth.

Used by the dce_config command.

DCE_SCP_PROCESS_NAME

Specifies the Guardian process name of the Subsystem Control Point (SCP) process to be contacted by all DCE processes in the virtual host. The default is

$ZNET.

If this variable is assigned a value, the $ character in the SCP process name must be preceded by the shell \ character, as in:

export DCE_SCP_PROCESS_NAME=\$ZNET1

If the specified process is not responding or not running, dce_config uses the default of $ZNET. However, DCE demons and other processes either do not

Hewlett-Packard Company 527186-003

Miscellaneous environ(5)

start or do not respond until the specified process is running.

DCE_SOCKET_REUSE

Specifies whether the IP address for the dced process is reused when the process is restarted. Valid values are:

0 (zero) The address is not reused.

1 The socket SO_REUSEADDR option is used at the time of binding port 135 so that even if the port is used by another process, dced restarts sucessfully.

The default is 0 (zero).

Used by the dce_config command.

DCED_ADMIN

Specifies whether the administrative group dced-admin should have permission to access and modify the access control lists that protect dced objects. Used by the dce_config command.

The value y allows the administrative group to access and modify local dced objects. If you use the value y, a privileged network user such as cell_admin is allowed local privileged access to the machine.

The value n restricts access and modification permission to the local host principal. If you use the value n, security is greater, but remote dced management is severely restricted.

The default is y.

DCEVH

Specifies the TCP/IP host name assigned to the virtual host for which operations are currently being performed. Used by the dce_config command, DCE demons, application servers, and clients.

The value specified for DCEVH is used when TCPIP_PROCESS_NAME is not specified.

If neither DCEVH nor TCPIP_PROCESS_NAME is specified, the default value of DCEVH is the name of the virtual host containing the /opt/dcelocal directory. If the /opt/dcelocal directory is not available, a default process name of /G/ZTC0 is assumed, and the default value of DCEVH is the hostname attribute of /G/ZTC0.

If TCPIP_PROCESS_NAME and DCEVH are both specified, the value specified for DCEVH is ignored, and the hostname attribute of the specified process is used.

DIR_REPLICATE

Controls the replication of CDS directories when an additional CDS server is being created at DCE configuration time. Used by the dce_config command.

Valid values are:

y

Causes dce_config to prompt for more directories to replicate

n

The default is n.

Suppresses further replication

527186-003 Hewlett-Packard Company 12

7

environ(5) OSS System Calls Reference Manual

DISPLAY_THRESHOLD

Specifies the messages to write to the standard output file.

Valid values are:

DEBUG

DETAIL

ERROR

WARNING

SUMMARY

VERBOSE

The default is SUMMARY.

Used by the dce_config command.

DO_CHECKS Controls whether the prompt

Press <RETURN> to continue, CTRL-C to exit: is returned when dce_config encounters a nonfatal error. This prompt forces the user to acknowledge the error and offers a way to exit dce_config.

Valid values are:

y

Displays the prompt

n

The default is y.

Does not display the prompt

When DO_CHECK has the value y during configuration of a security server and a security client, a check is made that a kerberos5 entry exists in

/G/system/ztcpip/services.

DTS_CONFIG

Specifies the type of configuration needed for a distributed time service (DTS) server during DCE client configuration. Used by the dce_config command.

Valid values are clerk, global, local, and none.

The default is clerk.

ECOBFE

EDITOR

Determines the pathname of the ecobol compiler. /G/system/system/ecobfe is | the default.

Specifies the inline editor used by the shell. If the value of this variable ends in

"vi" and the VISUAL variable is not assinged a variable, the corresponding inline editor option is enabled.

ELD

Specifies the pathname of the TNS/E linker for PIC code used by the compiler utilities to link object and library files into an executable program or dynamiclink library when linking is requested. By default, the program eld in the directory /usr/bin is used.

This environment variable is used for TNS/E-targeted compilations only.

EMS_COLLECTOR

Specifies alternate collector processes to the syslog( ) function.

12

8 Hewlett-Packard Company 527186-003

Miscellaneous environ(5)

ENV

Specifies the path used to find the script to be executed when the shell is invoked.

EXINIT

Provides a start-up list of commands read by the vi utility.

EXIT_ON_ERROR

Indicates whether dce_config exits in the event of a fatal error.

Valid values are:

y

Indicates that dce_config exits when it encounters a fatal error

n

Indicates that dce_config does not exit when it encounters a fatal error

The default is n.

This variable can help prevent a "here" file from getting out of sync with

dce_config.

Specifies the default editor used for the fc command.

FCEDIT

FPATH

Specifies the search path used for shell function definitions.

Guardian PARAMs

Specify the names and values of Guardian environment PARAMs, as known to the osh command. The names and values are converted from the Guardian environment PARAM names and values. See the osh(1) reference page for details.

HISTFILE

Specifies the pathname of the file used by the shell to store the command history.

HISTSIZE

Specifies the number of previously entered commands accessible to the shell.

HOME

Provides a user’s login directory.

HOST_NAME_IP

Specifies the IP address of the virtual host on which dce_config is running.

IFS

Specifies the internal field separators used in shell scripts.

JAVA_HOME Specifies the pathname for the most current installed version of the NonStop

Java Server environment.

KEYSEED

Specifies the character string used to seed the random key generator to create the master key for the master database and each slave database. Each database has its own master key and keyseed. Used in security server configuration by the

dce_config command.

LANG

Sets the locale to be used for all categories, unless overridden by LC_ALL,

LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY,

LC_NUMERIC, or LC_TIME environment variables. The LANG and LC_* environment variables can each have one of these values:

C

POSIX

For the C locale

For the POSIX locale

527186-003 Hewlett-Packard Company 12

9

environ(5) OSS System Calls Reference Manual

ll_TT.CODESET

ll

TT

CODESET

Is a 2-letter, lowercase abbreviation for the language name. The abbreviations come from

ISO 639. For example:

en

English

fr ja de

French

Japanese

German (from Deutsch)

Is a 2-letter, uppercase abbreviation for the territory name. The abbreviations come from ISO

3166. For example:

US

United States of America

JP

NL

ES

Japan

The Netherlands

Spain (from Espan˜a)

Is the name of the code set or encoding method.

For example:

ASCII

ISO8859-1

AJEC

ASCII

ISO 8859-1

Japanese EUC

Some examples of full locale names are:

en_US.ISO8859-1

English,

United States of America,

ISO 8859-1

fr_FR.ISO8859-1

French, France,

ISO 8859-1

fr_CH.ISO8859-1

French, Switzerland,

ja_JP.AJEC

ISO 8859-1

Japanese, Japan, EUC

LAN_NAME For a multiple-LAN configuration, specifies the internal name of the LAN (in the

LAN profile). Used in CDS server configuration by the dce_config command.

LC_ALL

Sets the locale for all categories and overrides any other locale environment variables set. See the description of LANG for locale name syntax.

LC_COLLATE

Sets the locale to be used for collating strings. See the description of LANG for locale name syntax.

LC_CTYPE

Sets the locale to be used for classifying characters. See the description of

LANG for locale name syntax.

LC_MESSAGES

Sets the locale to be used for displaying messages. See the description of LANG for locale name syntax.

12

10 Hewlett-Packard Company 527186-003

Miscellaneous environ(5)

LC_MONETARY

Sets the locale to be used for formatting monetary values. See the description of

LANG for locale name syntax.

LC_NUMERIC

Sets the locale to be used for formatting and parsing numeric values. See the description of LANG for locale name syntax.

LC_TIME

Sets the locale to be used for formatting and parsing date and time values. See the description of LANG for locale name syntax.

LD

Specifies the pathname of the TNS/R linker for PIC code used by the compiler utilities to link object and library files into an executable program or dynamiclink library when linking is requested. By default, the program ld in the directory /usr/bin is used. This environment variable is used for TNS/R-targeted compilations only.

LOCPATH

Specifies the sequence of directories, separated by colons, to be searched by the

iconv_open( ) function when looking for the table-driven iconv converter modules.

LOG_THRESHOLD

Specifies the minimum priority log messages to write to the log file,

/tmp/dce_config.log. Used by the dce_config command.

Valid values are:

DEBUG

DETAIL

ERROR

WARNING

SUMMARY

VERBOSE

The default is VERBOSE.

LOGNAME

Specifies the user’s login name, as known to the osh command. The value is converted from the Guardian PARAM LOGNAME.

MAKEFLAGS

Lists the environment variables for the make utility to process. Setting a variable in MAKEFLAGS overrides the setting of that variable in the shell.

MANPATH

Sets the path used by the man command to look for files to display. The default pathname is /usr/share/man.

MSGVERB

Defines which message components are sent by the fmtmsg( ) function to the standard error file.

MULTIPLE_LAN

Indicates whether to configure the node with multiple LAN capabilities.

Valid values are:

y

Indicates configure with multiple LAN capabilities

n

The default is n.

Indicates do not configure with multiple LAN capabilities

Used in CDS configuration by the dce_config command.

527186-003 Hewlett-Packard Company 12

11

environ(5) OSS System Calls Reference Manual

MXCMP

Determines the pathname of the NonStop SQL/MX release 1 compiler.

/G/system/system/mxcmp is the default.

Used by the compiler utilities.

MXCMPUM

Determines the pathname of the NonStop SQL/MX release 2 compiler.

/usr/tandem/sqlmx/bin/mxCompileUserModule is the default.

Used by the compiler utilities.

MXSQLC

MXSQLCO

Determines the pathname of the NonStop SQL/MX preprocessor, mxsqlco.

/usr/tandem/sqlmx/bin/mxsqlco is the default.

Used by the nmcobol command.

NLD

Determines the pathname of the NonStop SQL/MX preprocessor, mxsqlc.

/usr/tandem/sqlmx/bin/mxsqlc is the default.

Used by the c89 command.

Specifies the pathname of the non-PIC TNS/R linker used by the compiler utilities to link object and library files into an executable program or shared run-time library when linking is requested. By default, the program nld in the directory

/usr/bin is used.

This environment variable is used for TNS/R-targeted compilations only.

NLSPATH

Specifies the sequence of directories, separated by colons, to be searched by the

catopen( ) function when looking for message catalogs. The meanings of the variables in the NLSPATH environment variable are:

%N

%L

%l

%t

%c

The value passed in the name parameter of catopen( ).

The current locale name defined for the LC_MESSAGES category: for example, fr_BE.ISO8859-1.

The language element from the current locale name: for example, fr.

The territory element from the current locale name: for example,

BE.

The code-set element from the current locale name: for example,

ISO8859-1.

A single % (percent sign) character.

%%

PATH

Specifies the sequence of directories, separated by colons, to be searched by the

sh utility, the system command, the execvp( ) function, and so forth, when looking for an executable file. The osh command can convert the Guardian PARAM

PATH to this value.

PMSEARCHLIST

Specifies the values used by the gtacl command to resolve a Guardian file identifier.

PRINTER

Specifies the name of the default printer.

12

12 Hewlett-Packard Company 527186-003

Miscellaneous environ(5)

PS1

PS2

PS3

Specifies the primary prompt string used by the shell.

Specifies the secondary prompt string used by the shell.

Specifies the selection prompt string used by the shell within a loop.

PS4

PWD

Specifies the prompt string used by the shell during an execution trace.

Specifies the user’s initial working directory, as known to the osh command.

The value is converted from the Guardian PARAM PWD.

PWD_MGMT_SVR

Specifies the pathname of the Password Management server. The default value is /opt/dcelocal/bin/pwd_strengthd. Used in Password Management server configuration by the dce_config command.

PWD_MGMT_SVR_OPTIONS

Specifies the default options for the Password Management server

(pwd_strengthd). The value of the variable is set to -v (verbose) at server configuration.

Used by the dce_config command.

REMOVE_PREV_CONFIG

Indicates whether to remove all remnants of previous configurations before performing the new configuration.

Valid values are:

y n

Indicates remove all remnants

Indicates do not remove all remnants

If you set this variable to y, dce_config removes all configured components each time you configure any component, and you must reconfigure them all.

Used in all component configurations by the dce_config command.

REMOVE_PREV_INSTALL

Indicates whether to remove all remnants of previous DCE installations before performing the new install.

Valid values are:

y n

Indicates remove all remnants

Indicates do not remove all remnants

If you set this variable to y, dce_config automatically removes all installed components each time you install any component, and you must reinstall them all.

Used in all component installations by the dce_config command.

REP_CLEARINGHOUSE

Specifies the name for a new clearinghouse. Used in additional CDS server configuration by the dce_config command.

527186-003 Hewlett-Packard Company 12

13

environ(5) OSS System Calls Reference Manual

REPLICATE_ALL_DIRS

Specifies whether to replicate all directories from the master CDS server database to the additional CDS server database during additional CDS server configuration. Used by the dce_config command.

The value y indicates that all directories should be replicated.

The value n indicates that no directories should be replicated.

The default is n.

REPLICATE_DIR_LIST

Specifies a list of directories to be replicated. Used by the dce_config command.

Directory pathnames must be separated by one or more spaces, and the list of directories must be enclosed in quotation marks.

If this variable is not specified, the user is prompted for a directory list.

_RLD_FIRST_LIB_PATH

Specifies a list of directory pathnames to be searched by the rld loader before searching public libraries or locations specified by the linker. The list has a format similar to that of the PATH environment variable, with individual entries separated by colons (:).

For more information, see the dlopen(3) reference page.

_RLD_LIB_PATH

Specifies a list of directory pathnames to be searched by the rld loader before searching default locations. The list has a format similar to that of the PATH environment variable, with individual entries separated by colons (:).

For more information, see the dlopen(3) reference page.

SEC_REPLICA

Specifies the name of the security replica database. Used by the dce_config command.

The default value is the name of the host being configured.

SEC_SERVER

Specifies the name of the machine on which the cell’s master security server runs. Used in security client configuration by the dce_config command.

SHELL

Specifies the full pathname of the user’s login shell.

SOCKET_TRANSPORT_NAME

Specifies the process name of the OSS sockets transport provider process to be used by the inetd process.

SQLCFE

Specifies the pathname of the embedded NonStop SQL/MP preprocessor and compiler normally invoked by the c89 utility. By default, the program sqlcfe in the directory /usr/lib is used.

This environment variable is used for TNS/R-targeted compilations only.

SQLCOMP

Specifies the pathname of the final-stage NonStop SQL/MP compiler invoked by the c89 utility when embedded SQL is present and the program file is not a shared resource library file. By default, the program sqlcomp in the directory

/G/system/system is used.

12

14 Hewlett-Packard Company 527186-003

Miscellaneous environ(5)

SQLMX_PREPROCESSOR_VERSION

Indicates the preprocessor rules and features to be used. Specifying the value

800 causes rules and features associated with release 1.8 to be used; the mxcmp compiler is used and only MDF files and annotated source files are produced, while rules and features associated with release 2.0 and later are ignored. Specifying a value of 1200 or larger or not specifying a value causes rules and features associated with release 2.0 and later to be used; the mxCompileUserModule compiler is used and annotated source files that contain embedded module definitions are produced instead of MDF files, while restrictions associated with release 1.8 or earlier are ignored.

SWAPVOL

Specifies the disk volume used for working files by Guardian processes created by the TNS c89 utility. This variable must evaluate to a Guardian disk volume: for example, /G/scratch or $SCRATCH. By default, the user’s Guardian default volume is used.

SYNC_CLOCKS

Indicates whether to synchronize all client clocks with the security server clock.

Used by the dce_config command.

Valid values are:

y n

Indicates that client and server clocks will be synchronized

Indicates that client and server clocks will not be synchronized

If this variable is set to n and if clocks are out of synchronization by more than the value specified in the TOLERANCE_SEC variable, the user is prompted to synchronize them. This variable is valid only if the CHECK_TIME variable is set to y.

TANDEM_ALT_SRL

Controls whether the shared resource library is placed in an alternate location.

This value is a Guardian filename expressed in OSS pathname format and surrounded by quotation marks: for example, "/G/volume/subvol/ldce". The default is "", meaning that the shared resource library is placed in

/G/system/zdce/ldce.

Used by the dce_config command.

TANDEM_INSTALL_DIR

Specifies the location of the pax files for installation. This value is a Guardian subvolume name expressed in OSS pathname format and surrounded by quotation marks: for example, "/G/isv/zdce".

Used by the dce_config command.

TCPIP_PROCESS_NAME

Specifies the Guardian process name for the TCP/IP stack of the virtual host.

Used by the dce_config command.

If neither DCEVH nor TCPIP_PROCESS_NAME is specified, the default value of DCEVH is the name of the virtual host containing the /opt/dcelocal directory. If the /opt/dcelocal directory is not available, a default process name of /G/ZTC0 is assumed, and the default value of DCEVH is the hostname attribute of /G/ZTC0.

If TCPIP_PROCESS_NAME and DCEVH are both specified, the value specified for DCEVH is ignored, and the hostname attribute of the specified

527186-003 Hewlett-Packard Company 12

15

environ(5) OSS System Calls Reference Manual

process is used.

TCPIP_RESOLVER_NAME

Specifies the OSS pathname to be used instead of /etc/resolv.conf to identify the dynamic name server to be used when resolving Internet addresses. Equivalent to the Guardian environment DEFINE =TCPIPˆRESOLVERˆNAME.

TCPIP_RESOLVER_ORDER

Controls the search order for TCP/IPv6 when OSS socket calls require access to addresses for a given host. The /etc/ipnodes and /etc/hosts files are searched as follows by default:

If neither file exists, the domain name server (DNS) is checked for the host information.

For an IPv4 host address, /etc/ipnodes is checked; if the host is not found, /etc/hosts is checked.

For an IPv6 address, only /etc/ipnodes is checked.

For an IPv4 address, if /etc/hosts does not exist, the DNS is checked last.

When /etc/hosts exists, the values declared for the

TCPIP_RESOLVER_ORDER environment variable can be used to control the search as follows:

DNSONLY

Only the DNS is checked.

HOSTFILEONLY

Only /etc/hosts is checked.

DNS-HOSTFILE

The DNS is checked first; if the host is not found, /etc/hosts is checked.

HOSTFILE-DNS

/etc/hosts is checked first; if the host is not found, the DNS is checked.

TERM

Specifies the type of terminal for which output must be prepared. This information is used by commands, such as vi or more, that can exploit special terminal capabilities. (See the termcap(4) reference page for a list of terminal types.)

TERMCAP

Specifies a string describing the terminal in the TERM environment variable or, if it begins with a / (slash), the name of the termcap file. (See TERMPATH.)

This string applies only to programs using a termcap file (only for compatibility).

TERMINFO

Points to the directory containing terminfo database files. The tic command uses the value of this variable.

TERMPATH Specifies a sequence of pathnames of termcap files, separated by colons or spaces, which are searched for terminal descriptions in the order listed. The default is:

$HOME/.termcap:/usr/share/lib/termcap

TERMPATH is ignored if TERMCAP contains a full pathname. This string applies only to programs using the termcap file (only for compatibility).

12

16 Hewlett-Packard Company 527186-003

Miscellaneous environ(5)

TIME_SERVER

Specifies the virtual host that the security client will try to synchronize its clock against. This host must have a DTS server (dtsd) running on it. The recommended choice for the host is the one running the master security server (the name specified in the SEC_SERVER variable).

Used by the dce_config command.

TMOUT

TMPDIR

Specifies the number of seconds the shell waits for a response to a prompt before timing out.

Specifies a pathname that overrides the default directory for temporary files,

/tmp. (Used by the c89 utility.)

TOLERANCE_SEC

Specifies the number of seconds a client system clock can differ from the security server system clock before either the user is prompted to synchronize the clocks or the clocks are synchronized automatically.

The default is 120 seconds.

Both the security service and the CDS service require that there be no more than a 5-minute difference between the clocks on any two nodes in a cell.

Used by the dce_config command.

TOTAL_CLERKS

Specifies the number of CDS clerks for this host. On NonStop DCE systems,

CDS clerks are shared among users (unlike some other DCE systems, which use one CDS clerk for each user ID).

The default is 1.

Used by the dce_config command.

TZ

Specifies the time zone used by the shell and by time functions to override the default timezone. The value of TZ has the following form:

[:]stdoffset[dst[offset][,start[/time],end[/time]]]

std and dst

offset

Indicates no less than three, nor more than TZNAME_MAX, bytes that are the designation for the standard (std) or the alternative (dst, such as Daylight Savings Time) timezone. Only std is required; if dst is omitted, then the alternative time does not apply in this locale. Uppercase and lowercase letters are allowed. Any graphic characters except a leading colon (:) or digits, the comma (,), the minus sign (-), the plus sign (+), and the null character can appear in these fields.

If preceded by a -, the timezone is east of the Prime Meridian; otherwise, the timezone is west of the Prime Meridian (a condition that can be indicated by an optional preceding +).

Indicates the value to add to or subtract from the local time to arrive at Coordinated Universal Time. The offset has the form:

hh[:mm[:ss]]

The hour (hh) is required and can be a single digit. The minutes

(mm) and seconds (ss) are optional.

The offset following std is required. If no offset follows dst, the

527186-003 Hewlett-Packard Company 12

17

environ(5) OSS System Calls Reference Manual

alternative time is assumed to be one hour ahead of standard time. One or more digits can be used; the value is always interpreted as a decimal number. The hour is between 0 (zero) and

24, and the minutes (and seconds) are between 0 (zero) and 59.

Use of values outside these ranges causes undefined behavior.

date[/time],date[/time]

The rule that indicates when to change to and back from the alternative time, where the first date describes when the change from standard to alternative time occurs and the second date describes when the change back happens. Each time field describes when, in current local time, the change to the other time is made. The format of date is one of the following:

Jn The Julian day n in the range 1 through 365.

Leap days are not counted. That is, in all years including leap years, February 28 is day 59 and

March 1 is day 60. You cannot refer explicitly to February 29.

n

The zero-based Julian day in the range 0 through 365. Leap days are counted, and you can refer to February 29.

Mm.n.d The dth day (in the range 0 through 6) of week n

(in the range 1 through 5) of month m of the year

(in the range 1 through 12). Week 1 is the first week in which the day occurs. Week 5 means

"the last d day in month m, which might occur in either the fourth or the fifth week. Day zero is

Sunday.

time has the same format as offset except that no leading sign (- or +) is allowed. The default, if time is omitted, is 02:00:00.

UGEN

Specifies the pathname of the C or C++ compiler component used when binary assembly code is requested. By default, the program ugen in the directory

/usr/lib is used.

This environment variable is used for TNS/R-targeted compilations only.

UNCONFIG_HOST_PRESET

Specifies the name of the virtual host to be unconfigured. Used with the

unconfigure option by the dce_config command.

UOPT

Specifies the pathname of the C or C++ compiler component used when optimization is requested. By default, the program uopt in the directory /usr/lib is used.

This environment variable is used for TNS/R-targeted compilations only.

UPDATE_ALL_CLONES

Specifies whether the configurations of all existing clones of the current virtual host should be updated with the files being installed.

12

18 Hewlett-Packard Company 527186-003

Miscellaneous environ(5)

Valid values are:

y

Indicates that clones should be updated

n

The default is n.

Indicates that clones should not be updated

Used by the dce_config command.

USE_DEF_MSG_PATH

Specifies whether to use the default pathname when installing DCE message catalogs. Used by the dce_config command.

The value y indicates that message catalogs should be installed in the default directory /usr/lib/nls/msg/en_US.ISO8859-1.

The value n indicates that the user should be prompted to enter a directory pathname.

The default is y.

USER

Specifies the login name of the user.

UPDATE_DEFAULT_LIBDCESO

Specifies whether the default /usr/lib/libdce.so file should be updated with the shared run-time library being installed.

Valid values are:

UTILSGE

VISUAL

ZCPU y

Indicates that the update should occur

n

The default is n.

Indicates that it should not occur

This variable can be used by the dce_config command only for TNS versions of

NonStop DCE.

Specifies whether a shell utility attempts to include the /E or /G directories when recursively processing a pathname. This variable also can be tested by an application program to make the same determination.

Valid values are:

NOE

Do not include the /E directory.

NOG

Do not include the /G directory.

NOG:NOE

Do not include either the /E or /G directory.

The default includes both the /E and /G directories.

Specifies the inline editor used by the shell in visual mode.

Specifies the processor number of the processor executing the process for which

ZCPU was defined. This environment variable is set by the Kernel subsystem persistence manager for processes associated with process objects that are defined with the CPU ALL or CPU LIST attributes. If the variable is inherited by a process that has been spawned to another processor, the value might not be correct.

Additional names can be placed in the environment by the shell export command, by using

name=value arguments. It is unwise to change the values of certain shell variables that are

527186-003 Hewlett-Packard Company 12

19

environ(5) OSS System Calls Reference Manual

frequently exported by .profile files, such as PS1, PS2, and IFS.

RELATED INFORMATION

Commands: c89(1), dce_config(8) if installed, gtacl(1), osh(1), sh(1).

Functions: catopen(3), exec(2), getenv(3), iconv_open(3), putenv(3), syslog(3), tdm_execve(2),

tdm_execvep(2).

Files: termcap(4).

STANDARDS CONFORMANCE

HP extensions to the XPG4 Version 2 specification are:

The AS1, CCOMBE, CFE, COMP_ROOT, CRON_NAMED, EMS_COLLECTOR,

Guardian PARAMs, JAVA_HOME, LOCPATH, NLD, PMSEARCHLIST,

_RLD_FIRST_LIB_PATH, _RLD_LIB_PATH, SQLCFE, SQLCOMP, SWAPVOL,

UGEN, UOPT, UTILSGE, and ZCPU environment variables

All environment variables used by the dce_config utility

12

20 Hewlett-Packard Company 527186-003

Miscellaneous errno(5)

NAME

errno - Returns the error condition value

SYNOPSIS

#include <errno.h>

DESCRIPTION

The errno external variable contains the most recent error condition set by a function. The symbolic error names returned by a function and descriptions of each error condition are shown in the ERRORS section in the individual function reference pages. The errno.h header file contains a list of all symbolic error names and a one-line description of each.

The following is a list of the symbolic error names and the error condition each name describes:

[E2BIG] Argument list too long. The sum of the number of bytes used by the new process image’s argument list and environment list is greater than the allowed system limits.

[EACCES] Permission denied. The program attempted to access a file in a way forbidden by its file access permissions.

[EADDRINUSE]

Address in use. The program tried to allocate an address that is already allocated.

[EADDRNOTAVAIL]

Can’t assign requested address. The program tried to allocate an address that does not exist or cannot be allocated.

[EAFNOSUPPORT]

Address family not supported. The program requested an address in an address family not supported by the protocol family.

[EAGAIN] Resource temporarily unavailable. A system resource is temporarily unavailable, and later calls to the same routine might finish normally.

[EALREADY] Operation already in progress. The program attempted to begin an operation already in progress.

[EBADCF] C file not odd-unstructured. A C file (Guardian file code 180) is not an oddunstructured file.

[EBADDATA] Invalid data in buffer. A message buffer contains invalid data.

[EBADF] Bad file descriptor. A file descriptor parameter is out of range or refers to no open file, or a read (write) request is made to a file that is open only for writing

(reading).

[EBADFILE] File type not supported. A file access error occurred, or the file is of an unsupported type and cannot be opened.

[EBADMSG] An invalid message tag was found. There is no corresponding message for the message tag.

[EBADSYS] Invalid socket call. The program specified an unrecognized node name or node number in a socket call.

527186-003 Hewlett-Packard Company 12

21

errno(5) OSS System Calls Reference Manual

[EBIGDIR] The positioning within an OSS directory failed because there were more than

65535 file names beginning with the same two characters in the directory.

[EBUSY]

[ECHILD]

Mount device busy. The program attempted to use a system resource that is not currently available, because it is being used by another process in a manner that would conflict with the request being made by this process.

No child process. The wait( ) or waitpid( ) function was executed by a process that had no existing or unwaited-for child process.

[ECONNABORTED]

Software caused connection abort. Software on the connection path aborted the connection.

[ECONNREFUSED]

Connection refused. The other end of a requested connection refused to permit the connection to be made.

[ECONNRESET]

Connection reset by remote host. The connection was reset by the remote host.

[ECWDTOOLONG]

One of the following situations exists:

The pathname of the current working directory is longer than the PATH-

MAX value when the getcwd( ) function was called.

The length of the absolute pathname generated by the Guardian procedure call FILENAME_TO_PATHNAME_ is longer than

PATH_MAX.

The length of the absolute pathname generated by an internal Guardian procedure call is longer than PATH_MAX.

[EDEADLK] Deadlock condition. An attempt was made to lock a system resource that would have resulted in a deadlock situation.

[EDEFINEERR]

An error exists in a Guardian DEFINE.

[EDESTADDRREQ]

Destination request required. The program omitted a required destination address.

[EDOM]

[EEXIST]

[EFAULT]

[EFBIG]

Argument out of range. A function parameter evaluates to a value that is out of range (too large or too small).

File exists. An existing file was mentioned in an inappropriate context; for example, as a new link name in the link( ) function.

Bad address. The system detected an invalid address when attempting to use a parameter passed to a call.

File too large. The size of a file would exceed the maximum file size of an implementation.

12

22 Hewlett-Packard Company 527186-003

Miscellaneous errno(5)

[EFILEBAD] Corrupt Guardian file or bad EDIT file structure. The program used the open( ) or

read( ) function for an EDIT file (Guardian file code 101) in /G (the Guardian file system) that has an internal structure problem.

[EFSBAD]

[EFSERR]

Fileset catalog internal consistency error. The program attempted an operation involving a fileset with a corrupted fileset catalog.

File system internal error. The program attempted an operation that failed because of a system programming error. Follow site-defined procedures for reporting software problems.

[EGUARDIANLOCKED]

Guardian record or file locked. The program used the write( ) function for an object in /G (the Guardian file system) that has a record or file lock, resulting from a call to one of the following Guardian procedures:

LOCKFILE

LOCKREC

READLOCK

READLOCKX

READUPDATELOCK

READUPDATELOCKX

[EGUARDIANOPEN]

OSS rename( ) or unlink( ) function used on open Guardian file. An attempt was made to rename a file to an open Guardian file or to unlink a Guardian file opened with the Guardian FILE_OPEN_ procedure.

[EHAVEOOB] Out-of-band urgent data pending. Before receiving or sending normal data over a network connection, the program must read the out-of-band data by calling the

recv( ) function with the MSG_OOB flag set.

[EHLDSEM] A semaphore undo operation is occurring for an OSS process that has called a function in the tdm_exec or tdm_spawn set of functions to start a process in another processor.

[EHOSTDOWN]

Host is down. An access path has been broken or cannot be completed because a node has left the network.

[EHOSTUNREACH]

No route to host. No path exists to a node required by the process.

[EIDRM] Identifier removed. A required identifier has been removed.

[EILSEQ] Illegal byte sequence. An invalid wide character or a similarly invalid byte sequence has been detected.

[EINPROGRESS]

Operation in progress. A requested operation has begun.

[EINTR] Interrupted function call. An asynchronous signal was caught by the process during the execution of an interruptible function.

527186-003 Hewlett-Packard Company 12

23

errno(5) OSS System Calls Reference Manual

[EINVAL] Invalid function parameter. One of the following conditions exists:

The program supplied an invalid parameter value.

The system does not support execution of a new program file in the binary format used by a specified program file.

[EIO] I/O error. Some physical input or output error has occurred. Either a file cannot be opened because of an input or output error or data has been lost during an input or output transfer. This value is used only for errors on a program file, on a user library, on a shared run-time library, or during data transfer with a Guardian environment home terminal.

[EISCONN] Socket is connected. The program attempted to use a socket that is already in use.

[EISDIR] Is a directory. The program attempted to open an OSS directory with open( ) function write mode specified, or a directory in /G with any mode specified.

[EISGUARDIAN]

OSS operation on Guardian file descriptor. The program attempted an OSS operation involving a Guardian file descriptor.

[ELOOP]

[EMFILE]

Too many symbolic links. The program found too many symbolic links during pathname resolution.

Maximum number of files open. The program attempted to open more than the maximum number of file descriptors allowed in this process.

[EMLINK] Too many links. An attempt was made to have the link count of a single file exceed allowed system limits.

[EMSGQNOTRUNNING]

The OSS message-queue server for the requested message queue is not currently running.

[EMSGSIZE] Message too long. The specified message contained too many bytes.

[ENAMETOOLONG]

File name too long. One of the following is too long:

A pathname specified in a function call

A component of a pathname specified in a function call

The intermediate result of pathname resolution when a symbolic link is part of a pathname specified in a function call

Use the pathconf( ) function to obtain the applicable system limits.

[ENETDOWN]

Network down. The last path between the node and the network went down.

[ENETRESET] Network dropped connection on reset. The connection was dropped because the network was reset.

12

24 Hewlett-Packard Company 527186-003

Miscellaneous errno(5)

[ENETUNREACH]

Network unreachable. No path exists between the node and the network.

[ENFILE] File table overflow. Too many files are currently open in the system. The system has reached its predefined limit for simultaneously open files and temporarily cannot accept requests to open another one.

[ENOBUFS] Buffer space unavailable. No buffer space is available.

[ENOCPU] CPU unavailable. The program selected a processor that either does not exist, is down, or is unavailable for process creation.

[ENOCRE] Non-CRE process needs CRE-dependent service. The process is not compliant with the Common Run-Time Environment (CRE) but requested a service that depends on CRE.

[ENODATA] No data sent or received. No message or stream queue exists, or no data was sent or received.

[ENODEV] No such device. The program attempted to apply an inappropriate function to a device; for example, trying to read a write-only device, such as a printer.

[ENOENT] No such file, directory, or socket transport provider. A component of a specified pathname does not exist, the pathname is an empty string, a specified provider is no longer running, or a specified provider does not exist.

[ENOERR] No error occurred. This is the default value for errno.

[ENOEXEC] Executable program file format error. A request was made to execute a program file that, although it has the appropriate permissions, is not in the format required by the implementation for executable files.

[ENOIMEM] Insufficient internal memory. There is insufficient system code space in the processor to complete the operation.

[ENOLCK] No record locks available. A system-imposed limit on the number of simultaneous file and record locks has been reached, and no more are currently available.

[ENOMEM] Insufficient user memory. The new process image requires more memory than is allowed by the hardware or system-imposed memory management constraints.

[ENOMSG] No message. There is no message of the requested type.

[ENONSTOP] NonStop programming logic error exists. The program is written to use NonStop system features but has requested an operation incompatible with correct use of those features.

[ENOPROTOOPT]

Protocol not available. The requested protocol is not available.

[ENOREPLY] No reply in buffer. There is no reply in the message buffer.

[ENOROOT] Root fileset is not started. The program attempted an operation while the root fileset (fileset 0) was unavailable.

This error can occur after failure and restart of an OSS name server until the fileset has been repaired and remounted.

527186-003 Hewlett-Packard Company 12

25

errno(5) OSS System Calls Reference Manual

[ENOSPC] No space left on device. During the write( ) function on a regular file or when extending a directory, there is no free space left on the device.

[ENOSYS] Function not implemented. An attempt was made to use a function that is not available in this implementation.

[ENOTCONN] Socket not connected. The socket is not connected.

[ENOTDIR] Not a directory. The program attempted a directory operation on an object that is not a directory.

[ENOTEMPTY]

Directory not empty. A directory with entries other than . (dot) and . . (dot-dot) was supplied when an empty directory was expected.

[ENOTOSS] Not an OSS process. The program has called a function that can be called only from an OSS process.

[ENOTSOCK] Not a socket. The program attempted a socket operation on an object that is not a socket.

[ENOTSUP] Operation not supported on referenced object. The program attempted an operation that is not allowed on the referenced object.

[ENOTTY] Not a tty device. The program attempted a tty operation on an object that is not a tty device.

[ENXIO] No such device or address. An invalid device or address was specified during an input or output operation on a special file. One of the following events occurred:

A device was specified that does not exist, or a request was made beyond the limits of the device.

The fileset containing the requestor’s current working directory or root directory is not mounted. This error can occur after failure and restart of an OSS name server until the fileset has been repaired and remounted.

[EOPNOTSUPP]

Operation not supported on sockets. The program attempted to perform an operation that is not valid on a socket.

[EOSSNOTRUNNING]

Open System Services is not running or not installed. The program attempted an operation on an object in the OSS environment while a required system process was not available.

[EPARTIAL] Partial buffer received. Only a partial buffer of message data was received.

[EPERM] Not owner, permission denied. An attempt was made to perform an operation limited to processes with appropriate privileges or limited to the owner of a file or other resource.

[EPFNOSUPPORT]

Protocol family not supported. The program specified a protocol family that is not supported.

12

26 Hewlett-Packard Company 527186-003

Miscellaneous errno(5)

[EPIPE] Broken pipe or no reader on socket. The program attempted to write on a pipe,

FIFO, or socket for which there is no process to read the data.

[EPROTONOSUPPORT]

Protocol not supported. The program specified a protocol that is not supported.

[EPROTOTYPE]

Wrong protocol type. The program specified the wrong protocol for the type of socket.

[ERANGE] Value out of range. A program expression evaluated to a value that is out of range (too large or too small).

[EROFS] Read-only fileset. The program attempted to modify a file or directory on a fileset that is read only.

[ESHUTDOWN]

Can’t send after socket shutdown. The program attempted to send data after the socket shut down.

[ESOCKTNOSUPPORT]

Unsupported socket type. The program specified a socket type that is not supported.

[ESPIERR] SPI interface error. The Subsystem Programmatic Interface (SPI) used by an OSS component has returned an error indication.

[ESPIPE] Invalid seek. The program attempted to access the file offset associated with a pipe or FIFO.

[ESRCH] No such process or table entry. No process can be found corresponding to the given process ID.

[ETANOTRUNNING]

Transport agent not running. A transport-agent process for the requested socket is not running in the current processor.

[ETIMEDOUT]

Connection timed out. The timer for the connection expired.

[ETXTBSY] Object (text) file busy. The program attempted an operation on a program that is already busy.

[EUNKNOWN]

Unknown error. An unrecognized or very obscure error occurred. If this error occurs, follow site-defined procedures for reporting software problems to HP.

[EVERSION] Version mismatch. A version number mismatch exists.

[EWOULDBLOCK]

Operation would block. The operation requested by the program would block signal delivery.

[EWRONGID] One of the following conditions occurred:

The process attempted an operation through an operating system input/output process (such as a terminal server process) that has failed or is in the down state.

527186-003 Hewlett-Packard Company 12

27

errno(5) OSS System Calls Reference Manual

The processor for the disk process of the specified file failed during an input or output operation and takeover by the backup process occurred.

An open file descriptor has migrated to a new processor, but the new processor lacks a resource or system process needed for using the file descriptor.

[EXDEV] Cross-device link. The program attempted to link to a file on another fileset.

[EXDRDECODE]

XDR decoding error. An XDR decoding error occurred.

[EXDRENCODE]

XDR encoding error. An XDR encoding error occurred.

RELATED INFORMATION

Functions: perror(3), strerror(3).

STANDARDS CONFORMANCE

The following are HP extensions to the XPG4 Version 2 specification:

The errno values [EBADCF], [EBIGDIR], [ECWDTOOLONG], [EDEFINEERR],

[EFILEBAD], [EFSBAD], [EFSERR], [EGUARDIANLOCKED], [EGUARDIANO-

PEN], [EHLDSEM], [EISGUARDIAN], [EMSGQNOTRUNNING], [ENOCPU], [ENO-

CRE], [ENOIMEM], [ENONSTOP], [ENOROOT], [ENOTOSS], [ENOTSUP],

[EOSSNOTRUNNING], [ESPIERR], [ETANOTRUNNING], [EUNKNOWN], and

[EWRONGID] are supported.

12

28 Hewlett-Packard Company 527186-003

Miscellaneous filename(5)

NAME

filename, pathname - Explain OSS file system file naming

SYNOPSIS

For OSS files:

filename pathname

For local Guardian disk files used from the OSS environment:

/G/volume_name/subvolume_name/file_id

For local Guardian temporary disk files used from the OSS environment:

/G/volume_name/temp_file_id

For local Guardian nondisk devices used from the OSS environment:

/G/device_name/qualifier

For remote Guardian disk files used from the OSS environment:

/E/node_name/G/volume_name/subvolume_name/file_id

For remote Guardian temporary disk files used from the OSS environment:

/E/node_name/G/volume_name/temp_file_id

For remote Guardian nondisk devices used from the OSS environment:

/E/node_name/G/device_name/qualifier

PARAMETERS

filename pathname

Identifies a file at a relative location in the OSS file system. A filename value can be either a single filename or a symbolic link name.

A single filename is a character string of up to NAME_MAX (248) characters, including a null terminator. Valid characters preceeding the null terminator are described under OSS Filenames in DESCRIPTION, later in this reference page.

A symbolic link name is a string of up to NAME_MAX (248) characters, without a null terminator. Valid characters are described under OSS Filenames in DESCRIPTION, later in this reference page.

A symbolic link name is a pointer to one of the following:

• a single filename

• another symbolic link

• a pathname

Identifies a file in the OSS file system. A pathname has the following form:

[ / ] filename_1/filename_2 [ / . . . /filename_n ]

A pathname on a remote NonStop server node begins with /E/node_name/ and is expressed relative to the root directory on that node.

A pathname is a character string of up to PATH_MAX (1024) characters, including a null terminator. A pathname consists of one or more filename components, separated by slash (/) characters. Consecutive slashes are interpreted as

527186-003 Hewlett-Packard Company 12

29

filename(5) OSS System Calls Reference Manual

a single slash.

An absolute pathname begins with a slash character. An absolute pathname identifies an OSS file with respect to the current root directory.

A relative pathname does not begin with a slash character. A relative pathname identifies an OSS file with respect to the current working directory.

The filename_1 parameter specifies a directory. If filename_1 is a single period character (. , called dot), then filename_1 indicates the OSS current working directory.

If filename_1 is two period characters (. . , called dot-dot), then filename_1 indicates the parent directory of the OSS current working directory.

The filename_2 parameter specifies either another directory or the unique identifier for a file other than a directory within the filename_1 directory. If

filename_2 specifies a directory, then a filename_3 parameter can be specified, with the same constraints as for filename_2, and so on. The last filename_n parameter specified must uniquely identify a file that is not a directory.

All filename_n parameters must meet the requirements for the filename parameter.

node_name

Specifies the NonStop server node name used by the Expand product for access to files on other nodes. A node name is a character string of up to seven valid characters. Valid characters are the letters a through z and the digits 0 through 9.

(Uppercase letters A through Z are accepted but converted to lowercase letters.)

The first character must be a letter. Node names specified in the OSS file system do not begin with a backslash (\).

volume_name

Specifies the disk volume containing the file. A volume name is a character string of up to seven valid characters. Valid characters are the letters a through z and the digits 0 through 9. (Uppercase letters A through Z are accepted but converted to lowercase letters.) The first character must be a letter.

subvolume_name

Specifies the disk subvolume (prefix) of the file identifier. A subvolume name is a character string of up to eight valid characters. Valid characters are the letters a through z and the digits 0 through 9. (Uppercase letters A through Z are accepted but converted to lowercase letters.) The first character must be a letter.

file_id

Specifies the unique identifier of the file within its subvolume. A file identifier is a character string of up to eight valid characters. Valid characters are the letters a through z and the digits 0 through 9. (Uppercase letters A through Z are accepted but converted to lowercase letters.) The first character must be a letter.

temp_file_id

Specifies the unique identifier of the file within its disk volume. A temporary file identifier is a character string of two to eight valid characters. The first character must be a number sign (#). Valid characters for the rest of the string are the digits 0 through 9.

device_name

Specifies the name of the process providing the interface to the device. This name is a character string of up to seven valid characters. Valid characters are the letters a through z and the digits 0 through 9. (Uppercase letters A through Z are accepted but converted to lowercase letters.) The first character must be a letter.

12

30 Hewlett-Packard Company 527186-003

Miscellaneous filename(5)

qualifier

Specifies a unique identifier significant to the device. A qualifier is a character string of two to eight valid characters. The first character must be a number sign

(#). Valid characters for the rest of the string are the letters a through z, and the digits 0 through 9. (Uppercase letters A through Z are accepted but converted to lowercase letters.) The second character must be a letter.

DESCRIPTION

This reference page describes file-naming rules. There is a separate set of naming rules for the file system in each environment:

Rules for OSS files

Rules for Guardian files

There are also rules used to translate a name used in one environment to a name valid for the opposite environment.

OSS Filenames

In the OSS environment, the term "filename" refers to a component of a pathname that contains any characters other than a slash (/) character or a null character.

The hyphen (-) should not be the first character of an OSS filename if shell commands or utilities will be used on the file. The colon (:) should not be a character in an OSS filename if shell commands or utilities will be used on the file.

The OSS file system does not require filename characters to conform to POSIX.1 and ISO C standards for portable filenames. However, the use of portable filenames is strongly recommended.

Valid characters for a portable filename are the letters A through Z, the letters a through z, the digits 0 through 9, and the graphic symbols for period, underscore (_), and hyphen (-). The hyphen cannot be the first character of a portable filename.

Guardian Filenames

In the Guardian environment, the term "filename" refers to the set of information that uniquely identifies a Guardian object. A Guardian filename can contain the following characters:

The letters A through Z (lowercase letters are automatically translated to uppercase and do not appear in the Guardian file system)

The digits 0 through 9

The graphic symbols for backslash (\), number sign (#), colon (:), period, and dollar sign

($)

A Guardian filename is approximately equivalent to an OSS pathname; Guardian disk files appear in the /G directory with pathnames that have been mapped to OSS filenames.

Guardian objects with Guardian filenames include:

Disk files

Temporary disk files

Nondisk devices

Named processes

527186-003 Hewlett-Packard Company 12

31

filename(5) OSS System Calls Reference Manual

Unnamed processes

The type of object determines the syntax for the Guardian filename and which subset of the permitted characters is allowed in the parts of that filename.

For a disk file, the Guardian filename consists of the following four parts, separated by periods: node name A character string of two to eight valid characters, specifying the node within the

NonStop server Expand network. The first character must be a backslash (\).

Valid characters for the rest of the string are the letters A through Z and the digits 0 through 9. The second character must be a letter.

volume name A character string of two to eight valid characters, specifying the disk volume containing the file. The first character must be a dollar sign ($). Valid characters for the rest of the string are the letters A through Z and the digits 0 through 9.

The second character must be a letter.

subvolume name

A character string of up to eight valid characters, specifying the disk subvolume

(prefix) of the file identifier. Valid characters are the letters A through Z and the digits 0 through 9. The first character must be a letter.

file identifier A character string of up to eight valid characters, specifying the file. Valid characters are the letters A through Z and the digits 0 through 9. The first character must be a letter.

For a temporary disk file, the Guardian filename consists of the following three parts, separated by periods: node name A character string of two to eight valid characters, specifying the node within the

NonStop server Expand network. The first character must be a backslash (\).

Valid characters for the rest of the string are the letters A through Z and the digits 0 through 9. The second character must be a letter.

volume name A character string of two to eight valid characters, specifying the disk volume containing the file. The first character must be a dollar sign ($). Valid characters for the rest of the string are the letters A through Z and the digits 0 through 9.

The second character must be a letter.

temporary file identifier

A character string of two to eight valid characters, specifying the file. The first character must be a number sign (#). Valid characters for the rest of the string are the digits 0 through 9.

For a nondisk device, the Guardian filename consists of the following three parts, separated by periods: node name A character string of two to eight valid characters, specifying the node within the

NonStop server Expand network. The first character must be a backslash (\).

Valid characters for the rest of the string are the letters A through Z and the digits 0 through 9. The second character must be a letter.

device name A character string of two to eight valid characters, specifying the name of the process providing the interface to the device. The first character must be a dollar sign ($). Valid characters for the rest of the string are the letters A through Z and the digits 0 through 9. The second character must be a letter.

12

32 Hewlett-Packard Company 527186-003

Miscellaneous filename(5)

qualifier A character string of two to eight valid characters, specifying a unique identifier significant to the device. The first character must be a number sign (#). Valid characters for the rest of the string are the letters A through Z and the digits 0 through 9. The second character must be a letter.

For a named process, Guardian filename rules are complex. Guardian named processes are not accessible through the OSS file system, so the rules are not discussed here.

Guardian unnamed processes are not accessible through the OSS file system, so identification of them is not discussed here.

Refer to the Guardian Procedure Calls Reference Manual for more information about Guardian filenames.

Translating Guardian Filenames to OSS Filenames/Pathnames

Each portion of a Guardian filename is separately translated to a valid OSS filename. The resulting pathname is prefixed by /G/ for the local NonStop server node and by /E/node_name/G/ for a remote NonStop server node.

The OSS pathname for the Guardian filename of a disk file therefore becomes

/E/node_name/G/volume_name/subvolume_name/file_id. The /E/ prefix and node name is omitted from the translation for the /G directory on the local node.

The following character translations also occur:

Any dollar sign is deleted.

Periods are translated to slashes.

All uppercase letters are translated to lowercase as a normalizing convention. This translation allows filename pattern matching; pattern matching is case-sensitive in the OSS file system.

Translating OSS Filenames/Pathnames to Guardian Filenames

Each OSS filename within a pathname that includes the /G directory is translated to the appropriate part of a fully qualified Guardian filename. The OSS pathname for a file in the /G directory cannot contain more OSS filename components than the corresponding Guardian filename permits. Extra components cause an operation to fail; an errno value (described under ERRORS later in this reference page) is returned for function calls.

For a file on the local NonStop server node, the prefix /G/ is translated to the local node name.

For a file on a remote NonStop server node, the prefix /E/node_name/G/ is translated to the remote node name.

The OSS filenames . (dot) and . . (dot-dot) translate to the corresponding portions of an appropriately resolved OSS pathname when the current working directory is within a /G directory.

The following character translations also occur:

A dollar sign is prefixed to an OSS filename that corresponds to a Guardian volume name or to a Guardian process device name.

Periods, hyphens (-), and underscores (_) within OSS filenames are deleted.

OSS filenames longer than eight characters are truncated to seven or eight characters, as appropriate under Guardian filename rules.

527186-003 Hewlett-Packard Company 12

33

filename(5) OSS System Calls Reference Manual

Lowercase letters are not translated to uppercase for filename pattern matching. Pattern matching is case-insensitive in the Guardian file system.

Slashes between OSS filenames are translated to periods.

EXAMPLES

1.

The following is an example of an absolute OSS pathname:

/usr/ccomp/prog1.c

2.

The following is an example of an absolute OSS pathname:

/usr/ccomp/prog1.c

3.

The following is an example of an absolute OSS pathname for the file named prog2 on the remote NonStop server node NODE2:

/E/node2/usr/ccomp/prog2.c

4.

The following is a relative OSS pathname for a file in a subdirectory of the current working directory:

refman/ch1

5.

The following is an alternative relative OSS pathname for the same file in the same subdirectory of the current working directory:

. /refman/ch1

6.

The following is a relative OSS pathname for a file in a subdirectory of the parent directory of the current working directory:

. . /yourfiles/oldmail

7.

The following is an example of an absolute OSS pathname for a disk file in the Guardian file system with the Guardian filename \NODE1.$DATA1.MYSUBVOL.MYFILE:

/G/data1/mysubvol/myfile

8.

The following is an example of an absolute OSS pathname for a disk file in the Guardian file system on the remote node NODE2 with the Guardian filename

\NODE2.$DATA1.MYSUBVOL.MYFILE:

/E/node2/G/data1/mysubvol/myfile

9.

The following is an example of an absolute OSS pathname for a temporary disk file in the Guardian file system:

/G/guest/#7777777

10. The following is an example of an absolute OSS pathname for a Guardian nondisk device (a terminal device emulator):

/G/ztnt/#pty0001

11. The following is an example of translating an OSS pathname to a Guardian filename. If the OSS pathname /G/data.volume/src.l1.v3.4.8/properties.c is passed to an OSS function call, the OSS pathname is interpreted as if it were specified to be

/G/datavol/srcl1v34/properti. This interpretation translates to the Guardian filename

\LOCAL.$DATAVOL.SRCL1V34.PROPERTI, where \LOCAL is the node name for the local system in the NonStop server Expand network.

12

34 Hewlett-Packard Company 527186-003

Miscellaneous filename(5)

12. The following is an example of translating a Guardian filename to an OSS pathname. If

\LOCAL.$ZTNT.#PTY0001 is a nondisk device that needs to be passed to an OSS function, it can be referred to by specifying /G/ztnt/#pty0001.

NOTES

Guardian subvolume names and file identifiers beginning with the letter Z are reserved. Do not use such names for files in the /G directory.

During resolution of OSS pathnames, the st_atime field of the stat structure is updated for each parent directory involved in the resolution.

ERRORS

If an invalid Guardian filename results from OSS pathname or OSS filename translation for a file in the /G directory, a function call using the OSS pathname or OSS filename fails and one of the following values is returned for errno:

[EINVAL] The named file cannot be created.

[ENOENT] The named file cannot be opened.

Most OSS filename and pathname errors return the value [ENAMETOOLONG] for errno.

RELATED INFORMATION

Commands: ls(1), mv(1), rm(1).

Functions: creat(2), fstat(2), lstat(2), open(2), stat(2), symlink(2).

Files: limits(4).

Miscellaneous: hier(5).

STANDARDS CONFORMANCE

The following are HP extensions to the XPG4 Version 2 specification:

Characters in addition to those of the portable character set are supported in OSS filenames.

527186-003 Hewlett-Packard Company 12

35

hier(5) OSS System Calls Reference Manual

NAME

hier - Explains the OSS file system hierarchy

DESCRIPTION

This reference page describes the file system hierarchy. Subdirectories (and some files) are listed indented after the directory that they appear in.

/

/bin/

Root directory of the local OSS file system.

Utility program files, including system and internationalization utilities.

/dev/

unsupported/ Utilities and scripts believed to function correctly but which have not been thoroughly tested and therefore are not supported by HP. Use these utilities and scripts at your own discretion and risk. HP does not guarantee the behavior or performance of these utilities and is not obligated to fix problems associated with them.

/bin/unsupported/cat1/ contains reference page files for these utilities when reference pages exist for them. Use the command

man -M /bin/unsupported utility-name to read these reference pages.

Device directory, which contains only two devices:

/E/

/etc/ tty null

Current controlling terminal for the application that is running

Data sink

Directories and files for OSS and Guardian file systems on remote NonStop server nodes accessible through the Expand product. Do not mount filesets or create files here.

System configuration files (such as the default profile, termcap, and printcap files) and sockets-related network configuration files (such as the site-modified

hosts, networks, protocols, and services files). These are not executable files.

install_obsolete/

Files containing lists of files from earlier releases that HP recommends you remove from your system. These files can be used as input for the Pcleanup utility.

/G/

Guardian files. For example, the Guardian file $SYSTEM.SYSTEM.SCF

($volume.subvolume.fileid) is stored as /G/system/system/scf.

Each Guardian volume is a separate fileset. Guardian environment processes also appear in this directory. See the stat(2) reference page for additional information.

/lost+found/

Files located by the fileset checking program of the OSS Monitor. These have names of the form #inode_number, where inode_number identifies the inode number that is associated with the recovered file within the OSS file system.

/nonnative/

Files for use with G-series TNS or accelerated applications.

bin/

G-series TNS or accelerated files corresponding to the native files found in /bin/. The accelerated version of the c89 utility and the TNS C compiler are located here on G-series systems.

12

36 Hewlett-Packard Company 527186-003

Miscellaneous hier(5)

/tmp/

/usr/

/var/ usr/

G-series TNS or accelerated files corresponding to the native files found in /usr/.

System-generated temporary files (the contents of /tmp are usually not preserved across a system reboot).

User utilities and applications:

bin/ share/man/

Reference page files for use with the apropos,

man, and whatis commands when the corresponding G-series TNS or accelerated function or utility cannot be described in the reference page files found in /usr/share/man/.

Use the command man -M

/nonnative/usr/share/man topic to read these reference pages.

include/ lib/ share/

Native language and tools utilities, including the native c89 utility

C program header (include) files

C run-time library routines, internationalization message catalogs, locale conversion files, compiler components, and shared resource libraries

Text files, such as reference (man) page files

man/

Initially, the man/ directory contains:

cat1/ through cat8/

Preformatted Open System Services reference pages

whatis.frag/

The separately maintained portions of the whatis database

Files that increase in size until the size is deliberately reduced. Normally contains log files and similar files to which information is periodically appended.

RELATED INFORMATION

Commands: find(1), grep(1), ls(1).

Functions: stat(2).

Files: null(7).

527186-003 Hewlett-Packard Company 12

37

pathname(5)

NAME

pathname - Explains OSS file system path naming

DESCRIPTION

See the filename(5) reference page.

OSS System Calls Reference Manual

12

38 Hewlett-Packard Company 527186-003

Miscellaneous process_extension_results(5)

NAME

process_extension_results - Contains the status of a process creation attempt

SYNOPSIS

#include <tdmext.h> struct process_extension_results

∗∗

pr_results;

PARAMETERS

pr_results

Points to the output structure containing optional process identification and error information. In case of error, this structure provides additional information including the PROCESS_LAUNCH_ procedure error and error detail. The structure is defined in the tdmext.h header file.

The structure must be defined locally and initialized before its first use. Initialization is done using the #define

DEFAULT_PROCESS_EXTENSION_RESULTS, as defined in the tdmext.h header file.

DESCRIPTION

The process_extension_results structure contains status information after a call to the

tdm_execve( ), tdm_execvep( ), tdm_fork( ), tdm_spawn( ), or tdm_spawnp( ) function. This output structure is also used by Guardian environment procedures such as PROCESS_SPAWN_; therefore, some returned values defined in the tdmext.h header file are not returned to an OSS process and are not described in this reference page.

Not all of the returned values described in the following subsection are returned for a call to a specific OSS function.

The tdmext.h header file is not kept current when new error codes are defined for process creation functions. The list of _TPC_ macros described in this reference page is not complete; for a current description of error macros and error codes, see the Guardian header file

$SYSTEM.ZSPIDEF.ZGRDC or the summary of process-creation errors in the Guardian Pro-

cedure Calls Reference Manual (see the table entitled "Summary of Process Creation Errors").

Output Structure Information

If the pr_results parameter does not contain a null pointer, it points to an output structure defined in the tdmext.h header file. This structure can contain fields that vary from release to release, including reserved and filler fields.

First, the output structure must be initialized using the #define

DEFAULT_PROCESS_EXTENSION_RESULTS. This initialization sets the value of the

pr_len field to the correct value for the current release. The value of the pr_len field should not be modified after being set by #define DEFAULT_PROCESS_EXTENSION_RESULTS.

The following fields are meaningful in the current release:

typedef struct process_extension_results { long pr_len; short pr_phandle[10]; long pr_pid; long pr_errno; short pr_TPCerror; short pr_TPCdetail;

} process_extension_results_def;

|

527186-003 Hewlett-Packard Company 12

39

process_extension_results(5) OSS System Calls Reference Manual

RETURN VALUES

Upon successful completion of the function call, this structure returns the following information:

pr_len

Specifies the size in bytes of the structure. This value is the one specified as input.

pr_phandle

Contains the Guardian process handle of the new process.

pr_pid pr_errno

Contains the OSS process ID of the new process.

Contains the OSS error number normally returned in errno.

pr_TPCerror Identifies the process creation error. If the pr_results parameter of the function call did not contain a null pointer, the structure it points to returns additional error information including the PROCESS_LAUNCH_ error and error detail.

Refer to the ERRORS section of this reference page for a description of the returned information.

pr_TPCdetail Contains additional error information, as indicated in the descriptions of

pr_TPCerror field values. Refer to the ERRORS section of this reference page for a description of the returned information.

ERRORS

When an error occurs and the calling function provided a nonnull pointer for its pr_results parameter, one of the following values is returned in pr_TPCerror:

0 No error information is available. The contents of the pr_TPCdetail field are not meaningful.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ), tdm_spawn( ),

tdm_spawnp( ).

_TPC_BAD_PARAM_REFERENCE

A pointer value in a field in the structure pointed to by the pe_parms parameter of the calling function is invalid. Refer to error 3 in the discussion of

PROCESS_LAUNCH_ errors in the Guardian Procedure Errors and Messages

Manual for more information.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ), tdm_spawn( ),

tdm_spawnp( ).

The pr_TPCdetail field contains one of the following values to provide additional information:

_TPC_BAD_ARGV

The pointer to the argv[ ] array parameter of the calling function or one of the entries in the array is invalid.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_spawn( ),

tdm_spawnp( ).

_TPC_BAD_DEFINES

The pointer to the pe_defines field in the structure pointed to by the pe_parms parameter of the calling function is invalid.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ), tdm_spawnp( ).

12

40 Hewlett-Packard Company 527186-003

Miscellaneous

527186-003

process_extension_results(5)

_TPC_BAD_ENVIRON

One of the pointers in the environ array is invalid.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_spawn( ),

tdm_spawnp( ).

_TPC_BAD_ENVP

The pointer to the envp[ ] array parameter of the calling function or one of the entries in the array is invalid.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_spawn( ),

tdm_spawnp( ).

_TPC_BAD_ERROR_DETAIL

An internal OSS software error occurred. If the problem persists, follow site-defined procedures for reporting software problems to HP.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ).

_TPC_BAD_EXTENSION

The structure pointed to by the pe_parms parameter of the calling function and used in the function call is invalid.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ), tdm_spawnp( ).

_TPC_BAD_EXTSWAP

The pointer to the pe_extswap_file_name field in the structure pointed to by the pe_parms parameter of the calling function is invalid.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ), tdm_spawnp( ).

_TPC_BAD_FDMAP

The fd_map[ ] array parameter of the calling function is not valid for fd_count elements.

Issued for: tdm_spawn( ), tdm_spawnp( ).

_TPC_BAD_HOMETERM

The pointer to the pe_hometerm field in the structure pointed to by the pe_parms parameter of the calling function is invalid.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_spawn( ),

tdm_spawnp( ).

_TPC_BAD_INHERIT

The pointer to the inherit structure parameter of the calling function is invalid.

Issued for: tdm_spawn( ), tdm_spawnp( ).

_TPC_BAD_INTERNAL

An internal OSS software error occurred. If the problem persists, follow site-defined procedures for reporting software problems to HP.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ), tdm_spawnp( ).

Hewlett-Packard Company 12

41

process_extension_results(5) OSS System Calls Reference Manual

_TPC_BAD_OUTPUT

An internal OSS software error occurred. If the problem persists, follow site-defined procedures for reporting software problems to HP.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ).

_TPC_BAD_OUTPUT_LEN

An internal OSS software error occurred. If the problem persists, follow site-defined procedures for reporting software problems to HP.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ).

_TPC_BAD_PARMLIST

An internal OSS software error occurred. If the problem persists, follow site-defined procedures for reporting software problems to HP.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ), tdm_spawnp( ).

_TPC_BAD_PIMFILE

An internal OSS software error occurred. If the problem persists, follow site-defined procedures for reporting software problems to HP.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ), tdm_spawnp( ).

_TPC_BAD_PRIVATE_LIST

An internal OSS software error occurred. If the problem persists, follow site-defined procedures for reporting software problems to HP.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ), tdm_spawnp( ).

_TPC_BAD_PRIVLIST

An internal OSS software error occurred. If the problem persists, follow site-defined procedures for reporting software problems to HP.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ), tdm_spawnp( ).

_TPC_BAD_PROCESS_NAME

The pointer to the pe_process_name field in the structure pointed to by the pe_parms parameter of the calling function is invalid.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ), tdm_spawnp( ).

12

42 Hewlett-Packard Company 527186-003

Miscellaneous process_extension_results(5)

_TPC_BAD_SWAP

The pointer to the pe_swap_file_name field in the structure pointed to by the pe_parms parameter of the calling function is invalid.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ), tdm_spawnp( ).

_TPC_BAD_UC

The file parameter pointer of the calling function is invalid.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_spawn( ),

tdm_spawnp( ).

_TPC_BAD_UL

The pointer to the pe_library_name field in the structure pointed to by the pe_parms parameter of the calling function is invalid.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_spawn( ),

tdm_spawnp( ).

_TPC_BAD_PARAM_VALUE

Some combination of values for fields in the structure pointed to by the

pe_parms parameter of the calling function is invalid. Refer to error 2 in the discussion of PROCESS_LAUNCH_ errors in the Guardian Procedure Errors and

Messages Manual for more information.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ), tdm_spawn( ),

tdm_spawnp( ).

The pr_TPCdetail field contains one of the following values to provide additional information:

_TPC_BAD_CPU

The pe_cpu field in the structure pointed to by the pe_parms parameter of the calling function contains an invalid value.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ), tdm_spawnp( ).

_TPC_BAD_CREATE_OPTIONS

The pe_create_options field in the structure pointed to by the

pe_parms parameter of the calling function contains an invalid value.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ), tdm_spawnp( ).

_TPC_BAD_DEBUG_OPTIONS

The pe_debug_options field in the structure pointed to by the

pe_parms parameter of the calling function contains an invalid value.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ), tdm_spawnp( ).

527186-003 Hewlett-Packard Company 12

43

process_extension_results(5) OSS System Calls Reference Manual

_TPC_BAD_DEFINES

The pe_defines field in the structure pointed to by the pe_parms parameter of the calling function is invalid.

Issued for: tdm_execvep( ), tdm_fork( ), tdm_spawn( ),

tdm_spawnp( ).

_TPC_BAD_EXTENSION

The structure pointed to by the pe_parms parameter of the calling function and used in the function call is invalid.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ), tdm_spawnp( ).

_TPC_BAD_EXTSWAP

The pe_extswap_file_name field in the structure pointed to by the pe_parms parameter of the calling function contains an invalid OSS pathname for a Guardian file.

This error occurs only for G-series TNS or accelerated new process image files.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ), tdm_spawnp( ).

_TPC_BAD_HOMETERM

The pe_hometerm field in the structure pointed to by the

pe_parms parameter of the calling function points to an invalid

Guardian process name. Refer to error 14 in the discussion of file-system errors in the Guardian Procedure Errors and Mes-

sages Manual for more information.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ), tdm_spawnp( ).

_TPC_BAD_INHERIT

One of the fields in the inherit structure parameter of the calling function is invalid.

Issued for: tdm_spawn( ), tdm_spawnp( ).

_TPC_BAD_INTERNAL

An internal OSS software problem occurred. If the problem persists, follow site-defined procedures for reporting software problems to HP.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ), tdm_spawnp( ).

_TPC_BAD_INTERPRETER

The shell script contained in the text file pointed to by the file parameter of the calling function does not have an interpreter name in its #! header line.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_spawn( ),

tdm_spawnp( ).

12

44 Hewlett-Packard Company 527186-003

Miscellaneous

527186-003

process_extension_results(5)

_TPC_BAD_JOB

The pe_jobid field in the structure pointed to by the pe_parms parameter of the calling function contains an invalid value.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ), tdm_spawnp( ).

_TPC_BAD_MEM

The pe_memory_pages field in the structure pointed to by the

pe_parms parameter of the calling function contains an invalid value.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ), tdm_spawnp( ).

_TPC_BAD_NAME_OPTIONS

The pe_name_options field in the structure pointed to by the

pe_parms parameter of the calling function contains an invalid value.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ), tdm_spawnp( ).

_TPC_BAD_OSS_OPTIONS

The pe_OSS_options field in the structure pointed to by the

pe_parms parameter of the calling function contains an invalid value.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ), tdm_spawnp( ).

_TPC_BAD_OUTPUT

An internal OSS software error occurred. If the problem persists, follow site-defined procedures for reporting software problems to HP.

Issued for: tdm_spawn( ).

_TPC_BAD_OUTPUT_LEN

An internal OSS software error occurred. If the problem persists, follow site-defined procedures for reporting software problems to HP.

Issued for: tdm_spawn( ).

_TPC_BAD_PARMLIST

An internal OSS software error occurred. If the problem persists, follow site-defined procedures for reporting software problems to HP.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ), tdm_spawnp( ).

_TPC_BAD_PFS_SIZE

The pe_pfs_size field in the structure pointed to by the

pe_parms parameter of the calling function contains an invalid value.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ), tdm_spawnp( ).

Hewlett-Packard Company 12

45

process_extension_results(5)

12

46

OSS System Calls Reference Manual

_TPC_BAD_PIMFILE

An internal OSS software error occurred. If the problem persists, follow site-defined procedures for reporting software problems to HP.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ), tdm_spawnp( ).

_TPC_BAD_PRIO

The pe_priority field in the structure pointed to by the

pe_parms parameter of the calling function contains an invalid value.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ), tdm_spawnp( ).

_TPC_BAD_PRIVATE_LIST

An internal OSS software error occurred. If the problem persists, follow site-defined procedures for reporting software problems to HP.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ), tdm_spawnp( ).

_TPC_BAD_PRIVLIST

An internal OSS software error occurred. If the problem persists, follow site-defined procedures for reporting software problems to HP.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ), tdm_spawnp( ).

_TPC_BAD_PROCESS_NAME

The pe_process_name field in the structure pointed to by the

pe_parms parameter of the calling function points to an invalid

Guardian process name.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ), tdm_spawnp( ).

_TPC_BAD_SWAP

The pe_swap_file_name field in the structure pointed to by the

pe_parms parameter of the calling function points to an invalid

Guardian swap file name.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ), tdm_spawnp( ).

_TPC_BAD_UC

The file parameter value of the calling function cannot be resolved into a valid program file name.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ), tdm_spawnp( ).

_TPC_BAD_UL

The pe_library_name field value of the calling function cannot be resolved into a valid library file name.

Issued for: tdm_execve( ), tdm_execvep( ), tdm_fork( ),

tdm_spawn( ), tdm_spawnp( ).

Hewlett-Packard Company 527186-003

Miscellaneous process_extension_results(5)

For information about specific Guardian file-system errors, see the discussion of file-system errors in the Guardian Procedure Errors and Messages Manual.

RELATED INFORMATION

Functions: tdm_execve(2), tdm_execvep(2), tdm_fork(2), tdm_spawn(2), tdm_spawnp(2).

STANDARDS CONFORMANCE

This structure is an extension to the XPG4 Version 2 specification.

527186-003 Hewlett-Packard Company 12

47

spt_fputwc: Thread-aware fputwc( ) ....................................................................................... spt_fputwc(2)

required by spt_regFileIOHandler( ) /Executes callback type ............................................. spt_FileIOHandler_p(2)

spt_fputc: Thread-aware fputc( ) function ........................................................................ spt_fputc(2)

required by spt_regTimerHandler( ) function /callback type ............................................... spt_TimerHandler_p(2)

Renames a file (Guardian rename( ) function) rename_guardian: ...................................... rename_guardian(2)

a file or directory (OSS rename( ) function) rename_oss: Renames ............................... rename_oss(2)

Initiates thread-aware accept( ) function spt_accept: ................................................... spt_accept(2)

Initiates thread-aware close( ) function spt_close: ..................................................... spt_close(2)

Initiates thread-aware connect( ) function spt_connect: ................................................. spt_connect(2)

Initiates thread-aware fclose( ) function spt_fclose: .................................................... spt_fclose(2)

Initiates thread-aware fflush( ) function spt_fflush: ..................................................... spt_fflush(2)

Initiates thread-aware fgetc( ) function spt_fgetc: ..................................................... spt_fgetc(2)

Initiates thread-aware fgets( ) function spt_fgets: ...................................................... spt_fgets(2)

Initiates thread-aware fgetwc( ) function spt_fgetwc: .................................................. spt_fgetwc(2)

Initiates thread-aware fprintf( ) function spt_fprintf: ................................................... spt_fprintf(2)

Initiates thread-aware fputs( ) function spt_fputs: ..................................................... spt_fputs(2)

Initiates thread-aware fread( ) function spt_fread: ..................................................... spt_fread(2)

Initiates thread-aware fwrite( ) function spt_fwrite: .................................................... spt_fwrite(2)

Initiates thread-aware getc( ) function spt_getc: ....................................................... spt_getc(2)

Executes thread-aware getchar( ) function spt_getchar: ................................................. spt_getchar(2)

Initiates thread-aware gets( ) function spt_gets: ....................................................... spt_gets(2)

Initiates thread-aware getw( ) function spt_getw: ...................................................... spt_getw(2)

Initiates thread-aware getwc( ) function spt_getwc: .................................................... spt_getwc(2)

Initiates thread-aware getwchar( ) function spt_getwchar: .............................................. spt_getwchar(2)

Initiates thread-aware printf( ) function spt_printf: .................................................... spt_printf(2)

Initiates thread-aware putc( ) function spt_putc: ....................................................... spt_putc(2)

Initiates thread-aware putchar( ) function spt_putchar: ................................................. spt_putchar(2)

Initiates thread-aware puts( ) function. spt_puts: ...................................................... spt_puts(2)

Initiates thread-aware putw( ) function spt_putw: ..................................................... spt_putw(2)

Initiates thread-aware putwc( ) function spt_putwc: .................................................... spt_putwc(2)

Initiates thread-aware fputwchar( ) function spt_putwchar: .............................................. spt_putwchar(2)

Initiates thread-aware read( ) function spt_read: ....................................................... spt_read(2)

Initiates thread-aware readv( ) function spt_readv: ..................................................... spt_readv(2)

Initiates thread-aware recv( ) function spt_recv: ....................................................... spt_recv(2)

Initiates thread-aware recvfrom( ) function spt_recvfrom: ............................................... spt_recvfrom(2)

Initiates thread-aware select( ) function spt_select: .................................................... spt_select(2)

Initiates thread-aware send( ) function spt_send: ...................................................... spt_send(2)

Initiates thread-aware sendmsg( ) function spt_sendmsg: ............................................... spt_sendmsg(2)

Initiates thread-aware sendto( ) function spt_sendto: ................................................... spt_sendto(2)

Initiates thread-aware system( ) function spt_system: .................................................. spt_system(2)

Initiates thread-aware vfprintf( ) function spt_vfprintf: ................................................. spt_vfprintf(2)

Initiates thread-aware vprintf( ) function spt_vprintf: .................................................. spt_vprintf(2)

Initiates thread-aware waitpid( ) function spt_waitpid: ................................................. spt_waitpid(2)

Initiates thread-aware write( ) function spt_write: ..................................................... spt_write(2)

Initiate thread-aware writev( ) function spt_writev: ................................................... spt_writev(2)

SPT_ABORTTRANSACTION: Aborts and backs out a/ ................................................. SPT_ABORTTRANSACTION(3)

SPT_SERVERCLASS_DIALOG_ABORT_: Aborts the specified dialog ........................................... SPT_SERVERCLASS_DIALOG_ABORT_(3)

/Calculates an absolute expiration time ............................................... pthread_get_expiration_np(2)

Initiates thread-aware accept( ) function spt_accept: ...................................... spt_accept(2) on a socket accept: Accepts a new connection ............................... accept(2) socket accept: Accepts a new connection on a .................................... accept(2)

utime: Sets file access and modification times ...................................... utime(2) accessibility of a file access: Determines the .................................................. access(2)

527186-003 Hewlett-Packard Company Pindex

1

Pindex

2

OSS System Calls Reference Manual

chmod: Changes file access permissions ......................................................... chmod(2)

access: Determines the accessibility of a file ...................................................... access(2) signal sigaction: Specifies the action to take upon delivery of a .................................. sigaction(2) existing file/ link: Creates an additional directory entry for an .................................. link(2) specified/ /Obtains the stackbase address attribute of the .................................................. pthread_attr_getstackaddr(2)

/a shared memory segment to the address space of the calling/ ......................................... shmat(2)

but does not wait if the mutex is already locked /a specified mutex ............................... pthread_mutex_trylock(2) synchronous/ select: Selects among file descriptors for ............................................. select(2)

(library) file format ar: Describes the archive ............................................... ar(4)

cpio: Describes the extended cpio archive file format ......................................................... cpio(4)

tar: Describes the extended tar archive file format ......................................................... tar(4)

ar: Describes the archive (library) file format .......................................... ar(4)

/a file using a pathname, a set of argument strings, and an/ .............................................. execle(2)

/a file using a pathname, a set of argument strings, and **environ .................................. execl(2)

/a file using a filename, a set of argument strings, and **environ .................................. execlp(2)

/a file using a pathname, an argv array, and an envp array ....................................... execve(2)

/a file using a pathname, an argv array, and **environ ............................................. execv(2)

/a file using a filename, an argv array, and **environ ............................................. execvp(2)

an argv array, and an envp array /a file using a pathname, ..................................... execve(2)

strings, and an undeclared envp array /a set of argument ................................................ execle(2)

/a file using a pathname, an argv array, and an envp array ................................................ execve(2)

a file using a pathname, an argv array, and **environ /Executes ................................... execv(2)

a file using a filename, an argv array, and **environ /Executes ................................... execvp(2)

octal, hexadecimal, and decimal ASCII character sets /the .............................................. ascii(5) hexadecimal, and decimal ASCII/ ascii: Describes the octal, ............................................. ascii(5) special/ mknod: Creates a file or assigns a pathname to a character ................................ mknod(2)

/Obtains the thread-speci fic data associated with a key .................................................... pthread_getspecific(2)

/Sets the thread-speci fic data associated with a key .................................................... pthread_setspecific(2)

/and backs out a transaction associated with the current/ .......................................... SPT_ABORTTRANSACTION(3) process/ /Starts a new transaction associated with the current ........................................... SPT_BEGINTRANSACTION(3) process and/ /Ends the transaction associated with the current ........................................... SPT_ENDTRANSACTION(3) process/ /Restores a transaction associated with the current ........................................... SPT_RESUMETRANSACTION(3) to the address space of/ shmat: Attaches a shared memory segment ............................. shmat(2)

the status of a process creation attempt /Contains .......................................................... process_extension_results(5) mutex but/ pthread_mutex_trylock: Attempts to lock a specified ......................................... pthread_mutex_trylock(2)

pthread_getattr_np: Gets the attribute object for a thread .......................................... pthread_getattr_np(2) object /Obtains the mutex type attribute of a mutex attributes ...................................... pthread_mutexattr_getkind_np(2) object /Sets the mutex type attribute of a mutex attributes ...................................... pthread_mutexattr_setkind_np(2) object /Obtains the detachstate attribute of a thread attributes ...................................... pthread_attr_getdetachstate(2) object /Obtains the guardsize attribute of a thread attributes ...................................... pthread_attr_getguardsize_np(2)

/Obtains the inherit scheduling attribute of a thread attributes/ ..................................... pthread_attr_getinheritsched(2) object /of the scheduling policy attribute of a thread attributes ...................................... pthread_attr_getschedparam(2)

/Obtains the scheduling policy attribute of a thread attributes/ ..................................... pthread_attr_getschedpolicy(2) object /Obtains the stacksize attribute of a thread attributes ...................................... pthread_attr_getstacksize(2) object /Sets the detachstate attribute of a thread attributes ...................................... pthread_attr_setdetachstate(2) object /Sets the guardsize attribute of a thread attributes ...................................... pthread_attr_setguardsize_np(2)

/Sets the inherit scheduling attribute of a thread attributes/ ..................................... pthread_attr_setinheritsched(2) object /of the scheduling policy attribute of a thread attributes ...................................... pthread_attr_setschedparam(2)

/Sets the scheduling policy attribute of a thread attributes/ ..................................... pthread_attr_setschedpolicy(2) object /Sets the stacksize attribute of a thread attributes ...................................... pthread_attr_setstacksize(2)

/Obtains the stackbase address attribute of the specified thread/ ................................... pthread_attr_getstackaddr(2)

/Destroys a thread attributes object ............................................................. pthread_attr_destroy(2)

/Initializes a thread attributes object ............................................................. pthread_attr_init(2)

/Destroys a condition variable attributes object ............................................................. pthread_condattr_destroy(2)

/Initializes a condition variable attributes object ............................................................. pthread_condattr_init(2)

/Destroys a mutex attributes object ............................................................. pthread_mutexattr_destroy(2)

/Initializes a mutex attributes object ............................................................. pthread_mutexattr_init(2)

attribute of the specified thread attributes object /address .............................................. pthread_attr_getstackaddr(2)

detachstate attribute of a thread attributes object /Obtains the ....................................... pthread_attr_getdetachstate(2)

guardsize attribute of a thread attributes object /Obtains the ....................................... pthread_attr_getguardsize_np(2)

stacksize attribute of a thread attributes object /Obtains the ....................................... pthread_attr_getstacksize(2)

mutex type attribute of a mutex attributes object /Obtains the ....................................... pthread_mutexattr_getkind_np(2)

detachstate attribute of a thread attributes object /Sets the ............................................. pthread_attr_setdetachstate(2)

guardsize attribute of a thread attributes object /Sets the ............................................. pthread_attr_setguardsize_np(2)

stacksize attribute of a thread attributes object /Sets the ............................................. pthread_attr_setstacksize(2)

Hewlett-Packard Company 527186-003

Permuted Index

mutex type attribute of a mutex attributes object /Sets the ............................................. pthread_mutexattr_setkind_np(2)

scheduling attribute of a thread attributes object /the inherit ......................................... pthread_attr_getinheritsched(2)

scheduling attribute of a thread attributes object /the inherit ......................................... pthread_attr_setinheritsched(2)

policy attribute of a thread attributes object /the scheduling ................................. pthread_attr_getschedparam(2)

policy attribute of a thread attributes object /the scheduling ................................. pthread_attr_getschedpolicy(2)

policy attribute of a thread attributes object /the scheduling ................................. pthread_attr_setschedparam(2)

policy attribute of a thread attributes object /the scheduling ................................. pthread_attr_setschedpolicy(2)

/Writes modified data and file attributes to permanent storage .................................... fsync(2)

/Interrupts all threads awaiting input or output ............................................... spt_interrupt(2)

/Interrupts thread awaiting tagged I/O ....................................................... spt_interruptTag(2)

spt_wakeup: Wakes up a thread awaiting tagged I/O ....................................................... spt_wakeup(2)

spt_awaitio: Awaits a tagged I/O file ................................................ spt_awaitio(2)

/socket connections and limits the backlog of incoming connections ................................ listen(2)

SPT_ABORTTRANSACTION: Aborts and backs out a transaction/ ................................................. SPT_ABORTTRANSACTION(3)

bind: Binds a name to a socket ..................................... bind(2)

bind: Binds a name to a socket ............................................... bind(2)

sigsuspend: Changes the set of blocked signals and waits for a/ ................................... sigsuspend(2)

getsockname: Gets the locally bound name of a socket ................................................. getsockname(2)

/variable to be signaled or broadcast, or for a specific/ ........................................... pthread_cond_timedwait(2)

variable to be signaled or broadcast /specified condition ..................................... pthread_cond_wait(2)

Reads from a file into scattered buffers readv: ................................................................. readv(2)

Writes to a file from scattered buffers writev: ............................................................... writev(2) time pthread_get_expiration_np: Calculates an absolute expiration ................................ pthread_get_expiration_np(2)

thread-aware REPLYX procedure call spt_REPLYX: Initiates .......................................... spt_REPLYX(2)

the specified condition variable; callable only from an/ /waiting on .............................. pthread_cond_signal_int_np(2)

/Registers a user-supplied timer callback function ........................................................... spt_regTimerHandler(2)

descriptor to manage through a callback function /the file ............................................. spt_regOSSFileIOHandler(2)

spt_FileIOHandler_p: Executes callback type required by/ ............................................ spt_FileIOHandler_p(2)

spt_TimerHandler_p: Executes callback type required by/ ............................................ spt_TimerHandler_p(2)

spt_OSSFileIOHandler_p: Executes callback type required by the/ ...................................... spt_OSSFileIOHandler_p(2)

/fork-handler routines to be called when the calling thread’s/ ................................. pthread_atfork(2)

setgid: Sets the group ID of the calling process ............................................................... setgid(2)

setuid: Sets the user ID of the calling process ............................................................... setuid(2)

Gets the process group ID of the calling process getpgrp: ............................................... getpgrp(2)

to the address space of the calling process /memory segment ............................... shmat(2)

the scheduling priority of the calling process nice: Changes ...................................... nice(2)

pthread_exit: Terminates the calling thread ................................................................. pthread_exit(2)

the thread identi fier of the calling thread /Obtains ................................................. pthread_self(2)

cancelation request to the calling thread /of a pending ......................................... pthread_testcancel(2)

pthread_join: Causes the calling thread to wait for the/ ....................................... pthread_join(2)

pthread_setcancelstate: Sets the calling thread’s cancelability/ ...................................... pthread_setcancelstate(2)

pthread_setcanceltype: Sets the calling thread’s cancelability/ ...................................... pthread_setcanceltype(2)

/cleanup-handler routine from the calling thread’s cleanup-handler/ ................................. pthread_cleanup_pop(2)

/routines to be called when the calling thread’s process forks a/ ................................... pthread_atfork(2)

/Examines or changes the calling thread’s signal mask ......................................... pthread_sigmask(2) once by a single/ pthread_once: Calls a routine to be executed ...................................... pthread_once(2)

/Sets the calling thread’s cancelability state .......................................................... pthread_setcancelstate(2)

/Sets the calling thread’s cancelability type .......................................................... pthread_setcanceltype(2)

/Requests delivery of a pending cancelation request to the/ ............................................ pthread_testcancel(2)

termcap: Describes the terminal capability database ........................................................ termcap(4) for a/ pthread_cond_timedwait: Causes a thread to wait either ....................................... pthread_cond_timedwait(2) specified/ pthread_cond_wait: Causes a thread to wait for the ..................................... pthread_cond_wait(2) for the/ pthread_join: Causes the calling thread to wait ................................. pthread_join(2)

chmod: Changes file access permissions ................................... chmod(2)

ftruncate: Changes file length ........................................................ ftruncate(2) mask sigprocmask: Changes or examines the signal ................................... sigprocmask(2)

pthread_sigmask: Examines or changes the calling thread’s/ ........................................ pthread_sigmask(2) directory chdir: Changes the current working ........................................ chdir(2) directory chroot: Changes the effective root ............................................ chroot(2) of a file chown: Changes the owner and group IDs ............................... chown(2) of the calling process nice: Changes the scheduling priority .................................. nice(2) signals and waits/ sigsuspend: Changes the set of blocked ........................................... sigsuspend(2)

an interprocess communication channel pipe: Creates ................................................... pipe(2)

hexadecimal, and decimal ASCII character sets /the octal, ............................................... ascii(5)

a file or assigns a pathname to a character special file /Creates ...................................... mknod(2)

527186-003 Hewlett-Packard Company Pindex

3

OSS System Calls Reference Manual working directory chdir: Changes the current ............................................ chdir(2)

calling thread’s process forks a child process /be called when the ................................ pthread_atfork(2)

waitpid: Waits for a specific child process to stop or/ ................................................ waitpid(2)

wait: Waits for any child process to terminate ............................................. wait(2) permissions chmod: Changes file access .......................................... chmod(2) group IDs of a file chown: Changes the owner and .................................... chown(2) root directory chroot: Changes the effective ....................................... chroot(2)

process in a Pathway server class /a reply from a server ........................................... SPT_SERVERCLASS_SEND_(3)

SPT_SERVERCLASS_DIALOG_END_: Cleans up resources for the/ .......................................... SPT_SERVERCLASS_DIALOG_END_(3) calling/ /(Macro) Removes the cleanup-handler routine from the ................................. pthread_cleanup_pop(2) executed/ /(Macro) Establishes a cleanup-handler routine to be ....................................... pthread_cleanup_push(2)

/routine from the calling thread’s cleanup-handler stack and/ ........................................... pthread_cleanup_pop(2)

spt_close: Initiates thread-aware close( ) function ............................................................. spt_close(2)

close: Closes a file descriptor ....................................... close(2)

close: Closes a file descriptor .................................................. close(2)

pipe: Creates an interprocess communication channel ................................................ pipe(2)

socket: Creates an endpoint for communications ............................................................ socket(2)

pthread_equal: Compares two thread identi fiers ................................... pthread_equal(2)

the terminal interface for POSIX compatibility termios: Describes ................................ termios(4)

/Gets level of concurrency .................................................................... pthread_getconcurrency(2)

/Sets level of concurrency .................................................................... pthread_setconcurrency(2)

/Sets the number of concurrent TMF transactions ........................................ spt_setTMFConcurrentTransactions(2) used /Gets the number of concurrent TMF transactions being ............................. spt_getTMFConcurrentTransactions(2)

/Initializes the tfile for concurrent transaction management ............................ SPT_TMF_Init(2)

errno: Returns the error condition value .............................................................. errno(5)

pthread_cond_destroy: Destroys a condition variable .......................................................... pthread_cond_destroy(2)

pthread_cond_init: Initializes a condition variable .......................................................... pthread_cond_init(2)

that are waiting on the specified condition variable /all threads ..................................... pthread_cond_broadcast(2) object /Destroys a condition variable attributes ......................................... pthread_condattr_destroy(2) object /Initializes a condition variable attributes ......................................... pthread_condattr_init(2)

/that is waiting on the specified condition variable; callable only/ ................................ pthread_cond_signal_int_np(2)

that is waiting on the specified condition variable /one thread ..................................... pthread_cond_signal(2) or/ /a thread to wait either for a condition variable to be signaled ................................. pthread_cond_timedwait(2)

/thread to wait for the specified condition variable to be signaled/ ................................ pthread_cond_wait(2)

Initiates thread-aware connect( ) function spt_connect: ................................. spt_connect(2)

connect: Connects a socket ........................................... connect(2)

recv: Receives a message from a connected socket ........................................................... recv(2)

send: Sends a message on a connected socket ........................................................... send(2)

socketpair: Creates a pair of connected sockets .......................................................... socketpair(2)

accept: Accepts a new connection on a socket .................................................. accept(2)

listen: Listens for socket connections and limits the/ ........................................... listen(2)

limits the backlog of incoming connections /connections and ...................................... listen(2)

connect: Connects a socket .......................................................... connect(2)

math: Specifies the mathematical constants ......................................................................... math(4)

core: Is a file containing a memory image ......................................... core(4)

saveabend: Is a file containing a memory image ......................................... saveabend(4) variables used by signal/ signal: Contains definitions and ............................................... signal(4)

process_extension_results: Contains the status of a process/ .................................. process_extension_results(5)

environ: Contains the user environment ..................................... environ(5)

msgctl: Performs message control operations .......................................................... msgctl(2)

semctl: Performs semaphore control operations .......................................................... semctl(2)

shmctl: Performs shared memory control operations .......................................................... shmctl(2)

Sets the process group ID for job control setpgid: ............................................................. setpgid(2)

dup2: Duplicates and controls an open file descriptor .................................... dup2(2)

ioctl: Controls device files ...................................................... ioctl(2)

fcntl: Controls open file descriptors ....................................... fcntl(2) memory image core: Is a file containing a ............................................. core(4)

cpio: Describes the extended cpio archive file format ................................................. cpio(4) archive file format cpio: Describes the extended cpio ............................... cpio(4) the OSS environment or rewrites/ creat: Creates a regular file in ...................................... creat(2)

mkdir: Creates a directory ......................................................... mkdir(2) pathname to a character/ mknod: Creates a file or assigns a .............................................. mknod(2)

fork: Creates a new process ................................................... fork(2) extensions tdm_fork: Creates a new process with HP ..................................... tdm_fork(2) returns the ID of an/ semget: Creates a new semaphore set ID or .............................. semget(2)

Pindex

4 Hewlett-Packard Company 527186-003

527186-003

Permuted Index the process group ID setsid: Creates a new session and sets ..................................... setsid(2) segment or returns the/ shmget: Creates a new shared memory ...................................... shmget(2) sockets socketpair: Creates a pair of connected ........................................... socketpair(2) environment or rewrites/ creat: Creates a regular file in the OSS ................................... creat(2)

/a file for reading or writing, creates a regular file in the OSS/ .................................. open(2)

symlink: Creates a symbolic link to a file ................................... symlink(2)

pthread_create: Creates a thread ............................................................. pthread_create(2) entry for an existing file/ link: Creates an additional directory .................................... link(2) communications socket: Creates an endpoint for ................................................. socket(2) communication channel pipe: Creates an interprocess ................................................. pipe(2) for a message queue msgget: Creates or returns the identi fier .................................... msgget(2)

/Contains the status of a process creation attempt ............................................................. process_extension_results(5)

gets the value of the file mode creation mask umask: Sets and .................................... umask(2)

for an existing file on the current fileset /directory entry ...................................... link(2)

/a transaction associated with the current process and current/ .......................................... SPT_RESUMETRANSACTION(3)

transaction associated with the current process and current/ /new ................................ SPT_BEGINTRANSACTION(3)

a transaction associated with the current process and current/ /out ................................. SPT_ABORTTRANSACTION(3)

transaction associated with the current process and current/ /the ................................. SPT_ENDTRANSACTION(3)

Gets the effective user ID of the current process geteuid: ............................................... geteuid(2)

Gets the group list of the current process getgroups: ........................................... getgroups(2)

Gets the the real user ID of the current process getuid: ................................................. getuid(2)

to another thread in the current process /the processor ...................................... sched_yield(2) scheduling/ /Obtains the current scheduling policy and ...................................... pthread_getschedparam(2)

Gets information identifying the current system uname: .................................................. uname(2)

with the current process and current thread /associated ............................................. SPT_ABORTTRANSACTION(3)

with the current process and current thread /associated ............................................. SPT_BEGINTRANSACTION(3)

with the current process and current thread /associated ............................................. SPT_ENDTRANSACTION(3)

with the current process and current thread /associated ............................................. SPT_RESUMETRANSACTION(3)

SPT_TMF_GetTxHandle: Gets the current TMF transaction handle ................................... SPT_TMF_GetTxHandle(2)

chdir: Changes the current working directory ............................................. chdir(2) permanent/ fsync: Writes modified data and file attributes to ............................................... fsync(2)

/Obtains the thread-speci fic data associated with a key ............................................ pthread_getspecific(2)

/Sets the thread-speci fic data associated with a key ............................................ pthread_setspecific(2)

a unique thread-speci fic data key /Generates ....................................................... pthread_key_create(2)

Deletes a thread-speci fic data key pthread_key_delete: ...................................... pthread_key_delete(2)

null: Is a data sink file ................................................................... null(7)

Describes the terminal capability database termcap: ......................................................... termcap(4)

gettimeofday: Gets date and time .................................................................. gettimeofday(2)

/the octal, hexadecimal, and decimal ASCII character sets ....................................... ascii(5) be called when/ pthread_atfork: Declares fork-handler routines to ................................. pthread_atfork(2) signal/ signal: Contains definitions and variables used by ................................. signal(4)

pthread_delay_np: Delays execution of a thread ........................................ pthread_delay_np(2) key pthread_key_delete: Deletes a thread-specific data ....................................... pthread_key_delete(2)

Marks a thread object for deletion pthread_detach: .............................................. pthread_detach(2)

pthread_testcancel: Requests delivery of a pending cancelation/ ............................... pthread_testcancel(2)

Specifies the action to take upon delivery of a signal sigaction: ...................................... sigaction(2) file format ar: Describes the archive (library) ..................................... ar(4) archive file format cpio: Describes the extended cpio ......................................... cpio(4) archive file format tar: Describes the extended tar ............................................ tar(4) directories dir: Describes the format of ................................................. dir(4) and decimal ASCII/ ascii: Describes the octal, hexadecimal, ................................ ascii(5) database termcap: Describes the terminal capability ................................ termcap(4) for POSIX compatibility termios: Describes the terminal interface ................................... termios(4)

close: Closes a file descriptor ........................................................................ close(2)

dup: Duplicates an open file descriptor ........................................................................ dup(2)

/Sets interest in file descriptor ........................................................................ spt_setOSSFileIOHandler(2)

/Unregisters an OSS file descriptor ........................................................................ spt_unregOSSFileIOHandler(2)

and controls an open file descriptor dup2: Duplicates ......................................... dup2(2)

Waits on read-ready file descriptor spt_fd_read_ready: ..................................... spt_fd_read_ready(2)

Waits on write-ready file descriptor spt_fd_write_ready: .................................... spt_fd_write_ready(2) callback/ /Registers the file descriptor to manage through a .................................... spt_regOSSFileIOHandler(2)

fcntl: Controls open file descriptors ...................................................................... fcntl(2)

select: Selects among file descriptors for synchronous/ ........................................ select(2)

pthread_condattr_destroy: Destroys a condition variable/ ..................................... pthread_condattr_destroy(2)

pthread_cond_destroy: Destroys a condition variable ....................................... pthread_cond_destroy(2)

Hewlett-Packard Company Pindex

5

Pindex

6

OSS System Calls Reference Manual

pthread_mutex_destroy: Destroys a mutex ........................................................... pthread_mutex_destroy(2)

pthread_mutexattr_destroy: Destroys a mutex attributes/ ......................................... pthread_mutexattr_destroy(2) object pthread_attr_destroy: Destroys a thread attributes .......................................... pthread_attr_destroy(2)

shmdt: Detaches a shared memory segment ............................ shmdt(2) attributes object /Obtains the detachstate attribute of a thread ................................... pthread_attr_getdetachstate(2) attributes object /Sets the detachstate attribute of a thread ................................... pthread_attr_setdetachstate(2) file access: Determines the accessibility of a ................................. access(2) the out-of-band mark sockatmark: Determines whether a socket is at ................................ sockatmark(2)

ioctl: Controls device files ..................................................................... ioctl(2)

/Aborts the specified dialog .............................................................................. SPT_SERVERCLASS_DIALOG_ABORT_(3)

/up resources for the specified dialog after the server has ended/ ................................. SPT_SERVERCLASS_DIALOG_END_(3) message of the/ /Initiates the dialog and also sends the first ....................................... SPT_SERVERCLASS_DIALOG_BEGIN_(3) the/ /a send within the specified dialog to the server instance in ..................................... SPT_SERVERCLASS_DIALOG_SEND_(3)

/sends the first message of the dialog to the server instance in/ ................................... SPT_SERVERCLASS_DIALOG_BEGIN_(3) directories dir: Describes the format of .......................................... dir(4)

dir: Describes the format of directories ....................................................................... dir(4)

mkdir: Creates a directory ......................................................................... mkdir(2)

rename: Renames a file or directory ......................................................................... rename(2)

rmdir: Removes a directory ......................................................................... rmdir(2)

Changes the current working directory chdir: .............................................................. chdir(2)

Changes the effective root directory chroot: ........................................................... chroot(2) file/ link: Creates an additional directory entry for an existing ...................................... link(2) environment unlink: Removes a directory entry from the OSS ........................................ unlink(2)

rename_oss: Renames a file or directory (OSS rename( )/ ............................................. rename_oss(2)

/to lock a specified mutex but does not wait if the mutex is/ ....................................... pthread_mutex_trylock(2) descriptor dup: Duplicates an open file ......................................... dup(2) open file descriptor dup2: Duplicates and controls an ................................. dup2(2) descriptor dup: Duplicates an open file .................................................. dup(2) file descriptor dup2: Duplicates and controls an open .................................. dup2(2)

getegid: Gets the effective group ID .......................................................... getegid(2)

chroot: Changes the effective root directory .................................................. chroot(2) process geteuid: Gets the effective user ID of the current ..................................... geteuid(2) to be/ /Causes a thread to wait either for a condition variable ...................................... pthread_cond_timedwait(2)

dialog after the server has ended it /for the specified ............................................. SPT_SERVERCLASS_DIALOG_END_(3)

socket: Creates an endpoint for communications ....................................... socket(2) with the/ SPT_ENDTRANSACTION: Ends the transaction associated .................................... SPT_ENDTRANSACTION(3)

/Creates an additional directory entry for an existing file on/ ........................................ link(2)

unlink: Removes a directory entry from the OSS environment ................................. unlink(2) environment environ: Contains the user ........................................... environ(5)

a pathname, an argv array, and **environ /Executes a file using .................................. execv(2)

a filename, an argv array, and **environ /Executes a file using .................................. execvp(2)

a set of argument strings, and **environ /file using a filename, ................................. execlp(2)

a set of argument strings, and **environ /file using a pathname, ............................... execl(2)

environ: Contains the user environment ................................................................... environ(5)

/Creates a regular file in the OSS environment or rewrites an/ .......................................... creat(2)

creates a regular file in the OSS environment /reading or writing, ................................. open(2)

a directory entry from the OSS environment unlink: Removes ..................................... unlink(2)

strings, and an undeclared envp array /a set of argument ....................................... execle(2)

a pathname, an argv array, and an envp array /Executes a file using ................................. execve(2) condition value errno: Returns the error ................................................. errno(5)

errno: Returns the error condition value ..................................................... errno(5)

pthread_cleanup_push: (Macro) Establishes a cleanup-handler/ ..................................... pthread_cleanup_push(2) thread’s signal/ pthread_sigmask: Examines or changes the calling .................................. pthread_sigmask(2)

sigpending: Examines pending signals ............................................ sigpending(2)

sigprocmask: Changes or examines the signal mask ............................................. sigprocmask(2) functions that execute a file exec: Specifies a set of .................................................. exec(2) pathname, a set of argument/ execl: Executes a file using a ........................................ execl(2) pathname, a set of argument/ execle: Executes a file using a ...................................... execle(2) filename, a set of argument/ execlp: Executes a file using a ...................................... execlp(2)

Specifies a set of functions that execute a file exec: ........................................................ exec(2)

/Calls a routine to be executed once by a single thread ................................. pthread_once(2)

/a cleanup-handler routine to be executed when the thread/ ............................................ pthread_cleanup_push(2) a set of argument/ execlp: Executes a file using a filename, .................................. execlp(2) an argv array, and/ execvp: Executes a file using a filename, .................................. execvp(2) a set of argument/ execl: Executes a file using a pathname, ................................ execl(2)

Hewlett-Packard Company 527186-003

527186-003

Permuted Index a set of argument/ execle: Executes a file using a pathname, ................................ execle(2) an argv array, and/ execv: Executes a file using a pathname, ................................ execv(2) an argv array, and an/ execve: Executes a file using a pathname, ................................ execve(2) extensions tdm_execve: Executes a file with HP ................................................. tdm_execve(2) extensions tdm_execvep: Executes a file with HP ................................................. tdm_execvep(2) extensions tdm_spawn: Executes a new process with HP .................................. tdm_spawn(2) extensions tdm_spawnp: Executes a new process with HP .................................. tdm_spawnp(2) by/ spt_FileIOHandler_p: Executes callback type required ................................... spt_FileIOHandler_p(2) by the/ spt_OSSFileIOHandler_p: Executes callback type required ................................... spt_OSSFileIOHandler_p(2) by/ spt_TimerHandler_p: Executes callback type required ................................... spt_TimerHandler_p(2)

stack and optionally executes it /cleanup-handler ........................................ pthread_cleanup_pop(2) function spt_getchar: Executes thread-aware getchar( ) ................................. spt_getchar(2)

pthread_delay_np: Delays execution of a thread ..................................................... pthread_delay_np(2) specified/ spt_sleep: Suspends execution of the thread for a ......................................... spt_sleep(2) specified/ spt_usleep: Suspends execution of the thread for a ......................................... spt_usleep(2)

Requests that a thread terminate execution pthread_cancel: ........................................... pthread_cancel(2) pathname, an argv array, and/ execv: Executes a file using a ....................................... execv(2) pathname, an argv array, and an/ execve: Executes a file using a ..................................... execve(2) filename, an argv array, and/ execvp: Executes a file using a ..................................... execvp(2)

additional directory entry for an existing file on the current/ /an ................................... link(2)

OSS environment or rewrites an existing file /file in the .................................................. creat(2)

set ID or returns the ID of an existing semaphore set /semaphore ............................. semget(2)

/or returns the identi fier of an existing shared memory segment ................................. shmget(2)

_exit: Terminates a process .......................................... _exit(2)

/Calculates an absolute expiration time ............................................................... pthread_get_expiration_np(2)

or broadcast, or for a specific expiration time /to be signaled .................................... pthread_cond_timedwait(2) naming filename: Explain OSS file system file ......................................... filename(5) naming pathname: Explains OSS file system path ...................................... pathname(5) hierarchy hier: Explains the OSS file system ........................................ hier(5)

cpio: Describes the extended cpio archive file format ................................. cpio(4)

tar: Describes the extended tar archive file format .................................... tar(4)

Executes a file with HP extensions tdm_execve: ............................................... tdm_execve(2)

Executes a file with HP extensions tdm_execvep: ............................................. tdm_execvep(2)

Creates a new process with HP extensions tdm_fork: .................................................... tdm_fork(2)

Executes a new process with HP extensions tdm_spawn: ................................................ tdm_spawn(2)

Executes a new process with HP extensions tdm_spawnp: .............................................. tdm_spawnp(2)

Initiates thread-aware fclose( ) function spt_fclose: ....................................... spt_fclose(2) descriptors fcntl: Controls open file ................................................ fcntl(2)

Initiates thread-aware fflush( ) function spt_fflush: ......................................... spt_fflush(2)

spt_fgetc: Initiates thread-aware fgetc( ) function ............................................................. spt_fgetc(2)

spt_fgets: Initiates thread-aware fgets( ) function ............................................................. spt_fgets(2)

Initiates thread-aware fgetwc( ) function spt_fgetwc: ..................................... spt_fgetwc(2)

null: Is a data sink file ................................................................................... null(7)

/directory entry for an existing file on the current fileset ............................................... link(2)

read: Reads from a file ................................................................................... read(2)

spt_awaitio: Awaits a tagged I/O file ................................................................................... spt_awaitio(2)

spthread.h: Thread-aware header file ................................................................................... spthread.h(4)

write: Writes to a file ................................................................................... write(2)

Determines the accessibility of a file access: ...................................................................... access(2) times utime: Sets file access and modification .......................................... utime(2)

chmod: Changes file access permissions .................................................. chmod(2)

fsync: Writes modified data and file attributes to permanent/ .......................................... fsync(2)

the owner and group IDs of a file chown: Changes ...................................................... chown(2)

core: Is a file containing a memory image ................................... core(4)

saveabend: Is a file containing a memory image ................................... saveabend(4)

a pathname to a character special file /Creates a file or assigns ......................................... mknod(2)

close: Closes a file descriptor ................................................................. close(2)

dup: Duplicates an open file descriptor ................................................................. dup(2)

/Waits on read-ready file descriptor ................................................................. spt_fd_read_ready(2)

/Waits on write-ready file descriptor ................................................................. spt_fd_write_ready(2)

/Sets interest in file descriptor ................................................................. spt_setOSSFileIOHandler(2)

/Unregisters an OSS file descriptor ................................................................. spt_unregOSSFileIOHandler(2)

Duplicates and controls an open file descriptor dup2: ...................................................... dup2(2) a callback/ /Registers the file descriptor to manage through ................................ spt_regOSSFileIOHandler(2)

fcntl: Controls open file descriptors ................................................................ fcntl(2)

Hewlett-Packard Company Pindex

7

Pindex

8

OSS System Calls Reference Manual

select: Selects among file descriptors for synchronous/ .................................. select(2)

a set of functions that execute a file exec: Specifies ........................................................ exec(2)

or rewrites an existing file /file in the OSS environment ................................. creat(2) creates a regular/ open: Opens a file for reading or writing, ............................................. open(2)

Describes the archive (library) file format ar: ................................................................. ar(4)

the extended cpio archive file format cpio: Describes ........................................... cpio(4)

the extended tar archive file format tar: Describes .............................................. tar(4)

writev: Writes to a file from scattered buffers ............................................. writev(2)

information about an open file fstat: Provides ......................................................... fstat(2)

fileset information for an open file fstatvfs: Gets ........................................................... fstatvfs(2)

rename_guardian: Renames a file (Guardian rename( )/ ............................................... rename_guardian(2)

/or writing, creates a regular file in the OSS environment .......................................... open(2)

creat: Creates a regular file in the OSS environment or/ .................................... creat(2)

readv: Reads from a file into scattered buffers ............................................... readv(2)

ftruncate: Changes file length ....................................................................... ftruncate(2)

about a symbolic link or any file lstat: Provides information .................................... lstat(2)

Sets and gets the value of the file mode creation mask umask: .................................. umask(2)

filename: Explain OSS file system file naming ..................................................................... filename(5)

spt_regFile: Registers the file number ..................................................................... spt_regFile(2)

/Registers the file number ..................................................................... spt_regFileIOHandler(2) manages /Unregisters a Guardian file number as one that the user .................................... spt_unregFile(2)

Registers the Pathsend file number spt_regPathsendFile: ................................ spt_regPathsendFile(2) operation lseek: Sets file offset for read or write ............................................ lseek(2) character/ mknod: Creates a file or assigns a pathname to a ...................................... mknod(2)

rename: Renames a file or directory .............................................................. rename(2) function) rename_oss: Renames a file or directory (OSS rename( ) ................................... rename_oss(2)

ulimit: Sets and gets file size limits ................................................................. ulimit(2)

Provides information about a file stat: .......................................................................... stat(2)

Creates a symbolic link to a file symlink: ................................................................... symlink(2)

filename: Explain OSS file system file naming .................................................. filename(5)

hier: Explains the OSS file system hierarchy ..................................................... hier(5)

pathname: Explains OSS file system path naming ................................................ pathname(5) argument/ execlp: Executes a file using a filename, a set of ........................................ execlp(2) array, and/ execvp: Executes a file using a filename, an argv ........................................ execvp(2) argument/ execl: Executes a file using a pathname, a set of ...................................... execl(2) argument/ execle: Executes a file using a pathname, a set of ...................................... execle(2) array, and/ execv: Executes a file using a pathname, an argv ...................................... execv(2) array, and an/ execve: Executes a file using a pathname, an argv ...................................... execve(2)

tdm_execve: Executes a file with HP extensions ................................................. tdm_execve(2)

tdm_execvep: Executes a file with HP extensions ................................................. tdm_execvep(2)

execlp: Executes a file using a filename, a set of argument/ .......................................... execlp(2)

execvp: Executes a file using a filename, an argv array, and/ ......................................... execvp(2) file naming filename: Explain OSS file system ............................... filename(5)

Registers $RECEIVE filename spt_INITRECEIVE: ...................................... spt_INITRECEIVE(2)

ioctl: Controls device files .................................................................................. ioctl(2)

an existing file on the current fileset /directory entry for ............................................. link(2) file fstatvfs: Gets fileset information for an open ..................................... fstatvfs(2) pathname statvfs: Gets fileset information using a ............................................ statvfs(2) limits for floating-point/ float: Specifies the system ............................................. float(4)

Specifies the system limits for floating-point operations float: .................................... float(4)

fork: Creates a new process .......................................... fork(2)

Initiates a thread-aware fork() operation spt_fork: ............................................. spt_fork(2) called/ pthread_atfork: Declares fork-handler routines to be ........................................... pthread_atfork(2)

when the calling thread’s process forks a child process /be called .................................... pthread_atfork(2)

the archive (library) file format ar: Describes ...................................................... ar(4)

the extended cpio archive file format cpio: Describes ................................................. cpio(4)

dir: Describes the format of directories ...................................................... dir(4)

the extended tar archive file format tar: Describes .................................................... tar(4)

Initiates thread-aware fprintf( ) function spt_fprintf: ...................................... spt_fprintf(2)

spt_fputc: Thread-aware fputc( ) function ............................................................. spt_fputc(2)

spt_fputs: Initiates thread-aware fputs( ) function ............................................................. spt_fputs(2)

spt_fputwc: Thread-aware fputwc( ) ......................................................................... spt_fputwc(2)

/Initiates thread-aware fputwchar( ) function .................................................... spt_putwchar(2)

spt_fread: Initiates thread-aware fread( ) function ............................................................. spt_fread(2) an open file fstat: Provides information about ................................. fstat(2)

Hewlett-Packard Company 527186-003

527186-003

Permuted Index information for an open file fstatvfs: Gets fileset ....................................................... fstatvfs(2) file attributes to permanent/ fsync: Writes modified data and ................................... fsync(2)

ftruncate: Changes file length ....................................... ftruncate(2)

spt_fputc: Thread-aware fputc( ) function .......................................................................... spt_fputc(2)

by the spt_regOSSFileIOHandler( function /callback type required .................................. spt_OSSFileIOHandler_p(2)

by spt_regTimerHandler( ) function /callback type required .................................. spt_TimerHandler_p(2)

/Initiates thread-aware function for reading $RECEIVE .................................. spt_RECEIVEREAD(2)

a user-supplied timer callback function /Registers ........................................................ spt_regTimerHandler(2)

file or directory (OSS rename( ) function) rename_oss: Renames a ............................... rename_oss(2)

a file (Guardian rename( ) function) /Renames ....................................................... rename_guardian(2)

Initiates thread-aware accept( ) function spt_accept: ..................................................... spt_accept(2)

Initiates thread-aware close( ) function spt_close: ........................................................ spt_close(2)

Initiates thread-aware connect( ) function spt_connect: ................................................... spt_connect(2)

Initiates thread-aware fclose( ) function spt_fclose: ...................................................... spt_fclose(2)

Initiates thread-aware fflush( ) function spt_fflush: ....................................................... spt_fflush(2)

Initiates thread-aware fgetc( ) function spt_fgetc: ........................................................ spt_fgetc(2)

Initiates thread-aware fgets( ) function spt_fgets: ........................................................ spt_fgets(2)

Initiates thread-aware fgetwc( ) function spt_fgetwc: ..................................................... spt_fgetwc(2)

Initiates thread-aware fprintf( ) function spt_fprintf: ..................................................... spt_fprintf(2)

Initiates thread-aware fputs( ) function spt_fputs: ........................................................ spt_fputs(2)

Initiates thread-aware fread( ) function spt_fread: ........................................................ spt_fread(2)

Initiates thread-aware fwrite( ) function spt_fwrite: ...................................................... spt_fwrite(2)

Initiates thread-aware getc( ) function spt_getc: ......................................................... spt_getc(2)

Executes thread-aware getchar( ) function spt_getchar: .................................................... spt_getchar(2)

Initiates thread-aware gets( ) function spt_gets: ......................................................... spt_gets(2)

Initiates thread-aware getw( ) function spt_getw: ........................................................ spt_getw(2)

Initiates thread-aware getwc( ) function spt_getwc: ...................................................... spt_getwc(2)

thread-aware getwchar( ) function spt_getwchar: Initiates .................................. spt_getwchar(2)

Initiates thread-aware printf( ) function spt_printf: ....................................................... spt_printf(2)

Initiates thread-aware putc( ) function spt_putc: ......................................................... spt_putc(2)

Initiates thread-aware putchar( ) function spt_putchar: .................................................... spt_putchar(2)

Initiates thread-aware puts( ) function. spt_puts: ........................................................ spt_puts(2)

Initiates thread-aware putw( ) function spt_putw: ........................................................ spt_putw(2)

Initiates thread-aware putwc( ) function spt_putwc: ...................................................... spt_putwc(2)

thread-aware fputwchar( ) function spt_putwchar: Initiates .................................. spt_putwchar(2)

Initiates thread-aware read( ) function spt_read: ......................................................... spt_read(2)

Initiates thread-aware readv( ) function spt_readv: ....................................................... spt_readv(2)

Initiates thread-aware recv( ) function spt_recv: ......................................................... spt_recv(2)

thread-aware recvfrom( ) function spt_recvfrom: Initiates .................................. spt_recvfrom(2)

Initiates thread-aware recvmsg(2) function spt_recvmsg: .................................................. spt_recvmsg(2)

Initiates thread-aware select( ) function spt_select: ....................................................... spt_select(2)

Initiates thread-aware send( ) function spt_send: ......................................................... spt_send(2)

Initiates thread-aware sendmsg( ) function spt_sendmsg: .................................................. spt_sendmsg(2)

Initiates thread-aware sendto( ) function spt_sendto: ..................................................... spt_sendto(2)

Initiates thread-aware system( ) function spt_system: ..................................................... spt_system(2)

thread-aware vfprintf( ) function spt_vfprintf: Initiates .................................... spt_vfprintf(2)

Initiates thread-aware vprintf( ) function spt_vprintf: ..................................................... spt_vprintf(2)

Initiates thread-aware waitpid( ) function spt_waitpid: ................................................... spt_waitpid(2)

Initiates thread-aware write( ) function spt_write: ........................................................ spt_write(2)

Initiate thread-aware writev( ) function spt_writev: ..................................................... spt_writev(2)

to manage through a callback function /the file descriptor .......................................... spt_regOSSFileIOHandler(2)

and variables used by signal functions /Contains definitions .................................... signal(4)

exec: Specifies a set of functions that execute a file .......................................... exec(2)

Initiates thread-aware fwrite( ) function spt_fwrite: ....................................... spt_fwrite(2)

tty: Is the general terminal interface ............................................. tty(7)

pthread_key_create: Generates a unique/ ....................................................... pthread_key_create(2)

spt_getc: Initiates thread-aware getc( ) function .............................................................. spt_getc(2)

Executes thread-aware getchar( ) function spt_getchar: ................................... spt_getchar(2)

ID getegid: Gets the effective group ................................. getegid(2)

ID of the current process geteuid: Gets the effective user .................................... geteuid(2)

getgid: Gets the real group ID ...................................... getgid(2) the current process getgroups: Gets the group list of .................................. getgroups(2) local host gethostname: Gets the name of the .............................. gethostname(2)

getlogin: Gets login name ............................................ getlogin(2) peer socket getpeername: Gets the name of the .............................. getpeername(2)

Hewlett-Packard Company Pindex

9

Pindex

10

OSS System Calls Reference Manual

ID for a specified OSS process getpgid: Gets the process group ................................... getpgid(2)

ID of the calling process getpgrp: Gets the process group ................................... getpgrp(2)

getpid: Gets the OSS process ID .................................. getpid(2) process ID getppid: Gets the parent OSS ....................................... getppid(2) scheduling priority getpriority: Gets the OSS process ................................ getpriority(2)

spt_gets: Initiates thread-aware gets( ) function ............................................................... spt_gets(2)

gettimeofday: Gets date and time ......................................................... gettimeofday(2)

ulimit: Sets and gets file size limits ......................................................... ulimit(2) open file fstatvfs: Gets fileset information for an ...................................... fstatvfs(2) pathname statvfs: Gets fileset information using a ................................... statvfs(2) current system uname: Gets information identifying the .................................. uname(2)

pthread_getconcurrency: Gets level of concurrency ............................................. pthread_getconcurrency(2)

getlogin: Gets login name ............................................................. getlogin(2)

getsockopt: Gets socket options ....................................................... getsockopt(2) thread pthread_getattr_np: Gets the attribute object for a ....................................... pthread_getattr_np(2) handle SPT_TMF_GetTxHandle: Gets the current TMF transaction ................................ SPT_TMF_GetTxHandle(2)

getegid: Gets the effective group ID ........................................... getegid(2) current process geteuid: Gets the effective user ID of the ................................... geteuid(2) current process getgroups: Gets the group list of the ............................................... getgroups(2) socket getsockname: Gets the locally bound name of a ................................. getsockname(2)

socket_transport_name_get: Gets the name of the/ .................................................... socket_transport_name_get(2)

gethostname: Gets the name of the local host .................................... gethostname(2)

getpeername: Gets the name of the peer socket .................................. getpeername(2)

spt_getTMFConcurrentTransactions: Gets the number of concurrent TMF/ .......................... spt_getTMFConcurrentTransactions(2)

getpid: Gets the OSS process ID ............................................... getpid(2) priority getpriority: Gets the OSS process scheduling ................................. getpriority(2)

getppid: Gets the parent OSS process ID ................................... getppid(2) specified OSS process getpgid: Gets the process group ID for a .................................... getpgid(2) calling process getpgrp: Gets the process group ID of the .................................. getpgrp(2)

getgid: Gets the real group ID ................................................... getgid(2) current process getuid: Gets the the real user ID of the ..................................... getuid(2) creation mask umask: Sets and gets the value of the file mode ...................................... umask(2) bound name of a socket getsockname: Gets the locally ..................................... getsockname(2)

getsockopt: Gets socket options ................................... getsockopt(2)

gettimeofday: Gets date and time ................................ gettimeofday(2) of the current process getuid: Gets the the real user ID ................................... getuid(2)

spt_getw: Initiates thread-aware getw( ) function ............................................................. spt_getw(2)

spt_getwc: Initiates thread-aware getwc( ) function ........................................................... spt_getwc(2)

/Initiates thread-aware getwchar( ) function ...................................................... spt_getwchar(2)

/Unlocks the threads global mutex .................................................................. pthread_unlock_global_np(2)

pthread_lock_global_np: Locks the global mutex for threads ............................................... pthread_lock_global_np(2)

getegid: Gets the effective group ID ......................................................................... getegid(2)

getgid: Gets the real group ID ......................................................................... getgid(2)

getpgid: Gets the process group ID for a specified OSS/ ....................................... getpgid(2)

setpgid: Sets the process group ID for job control ................................................ setpgid(2)

getpgrp: Gets the process group ID of the calling process .................................... getpgrp(2)

setgid: Sets the group ID of the calling process .................................... setgid(2)

new session and sets the process group ID setsid: Creates a ............................................ setsid(2)

chown: Changes the owner and group IDs of a file .......................................................... chown(2)

getgroups: Gets the group list of the current process ................................... getgroups(2)

Sends a signal to a process or group of processes kill: ................................................ kill(2) the/ spt_unregFile: Unregisters a Guardian file number as one that ................................. spt_unregFile(2)

rename_guardian: Renames a file (Guardian rename( ) function) ...................................... rename_guardian(2) attributes object /Obtains the guardsize attribute of a thread ...................................... pthread_attr_getguardsize_np(2) attributes object /Sets the guardsize attribute of a thread ...................................... pthread_attr_setguardsize_np(2)

Gets the current TMF transaction handle SPT_TMF_GetTxHandle: ................................ SPT_TMF_GetTxHandle(2)

Sets the TMF transaction handle SPT_TMF_SetTxHandle: ................................. SPT_TMF_SetTxHandle(2)

spthread.h: Thread-aware header file ....................................................................... spthread.h(4)

ascii: Describes the octal, hexadecimal, and decimal ASCII/ ............................... ascii(5) system hierarchy hier: Explains the OSS file ............................................ hier(5)

Explains the OSS file system hierarchy hier: ............................................................... hier(5)

Gets the name of the local host gethostname: ......................................................... gethostname(2)

tdm_execve: Executes a file with HP extensions ................................................................ tdm_execve(2)

tdm_execvep: Executes a file with HP extensions ................................................................ tdm_execvep(2)

Creates a new process with HP extensions tdm_fork: .............................................. tdm_fork(2)

Hewlett-Packard Company 527186-003

Permuted Index

Executes a new process with HP extensions tdm_spawn: .......................................... tdm_spawn(2)

Executes a new process with HP extensions tdm_spawnp: ........................................ tdm_spawnp(2)

getegid: Gets the effective group ID .................................................................................... getegid(2)

getgid: Gets the real group ID .................................................................................... getgid(2)

getpid: Gets the OSS process ID .................................................................................... getpid(2)

getpgid: Gets the process group ID for a specified OSS process ..................................... getpgid(2)

setpgid: Sets the process group ID for job control ........................................................... setpgid(2)

Gets the parent OSS process ID getppid: .................................................................... getppid(2)

/semaphore set ID or returns the ID of an existing semaphore set ................................... semget(2)

getpgrp: Gets the process group ID of the calling process ............................................... getpgrp(2)

setgid: Sets the group ID of the calling process ............................................... setgid(2)

setuid: Sets the user ID of the calling process ............................................... setuid(2)

geteuid: Gets the effective user ID of the current process ............................................... geteuid(2)

getuid: Gets the the real user ID of the current process ............................................... getuid(2)

/Creates a new semaphore set ID or returns the ID of an/ ............................................. semget(2)

and sets the process group ID setsid: Creates a new session .................................. setsid(2)

msgget: Creates or returns the identi fier for a message queue ...................................... msgget(2)

/memory segment or returns the identi fier of an existing shared/ .................................... shmget(2)

pthread_self: Obtains the thread identifier of the calling thread ...................................... pthread_self(2)

Compares two thread identifiers pthread_equal: ............................................. pthread_equal(2)

uname: Gets information identifying the current system ...................................... uname(2)

Changes the owner and group IDs of a file chown: ....................................................... chown(2)

Is a file containing a memory image core: .................................................................... core(4)

Is a file containing a memory image saveabend: .......................................................... saveabend(4)

and limits the backlog of incoming connections /connections ............................ listen(2) long tag spt_generateTag: Increments and returns a static ..................................... spt_generateTag(2)

stat: Provides information about a file ................................................. stat(2) or any file lstat: Provides information about a symbolic link ............................... lstat(2)

fstat: Provides information about an open file ..................................... fstat(2) server-class send/ /Returns information about the last ............................................. SPT_SERVERCLASS_SEND_INFO_(3)

fstatvfs: Gets fileset information for an open file .......................................... fstatvfs(2) current system uname: Gets information identifying the .......................................... uname(2)

statvfs: Gets fileset information using a pathname ...................................... statvfs(2) thread attributes/ /Obtains the inherit scheduling attribute of a ................................... pthread_attr_getinheritsched(2) thread attributes/ /Sets the inherit scheduling attribute of a ................................... pthread_attr_setinheritsched(2)

pthread_condattr_init: Initializes a condition variable/ ................................... pthread_condattr_init(2)

pthread_cond_init: Initializes a condition variable ..................................... pthread_cond_init(2)

pthread_mutex_init: Initializes a mutex ......................................................... pthread_mutex_init(2) object pthread_mutexattr_init: Initializes a mutex attributes ........................................ pthread_mutexattr_init(2) object pthread_attr_init: Initializes a thread attributes ........................................ pthread_attr_init(2) concurrent/ SPT_TMF_Init: Initializes the tfile for .................................................... SPT_TMF_Init(2) function spt_writev: Initiate thread-aware writev( ) ...................................... spt_writev(2)

SPT_SERVERCLASS_DIALOG_SEND_: Initiates a send within the/ ............................................ SPT_SERVERCLASS_DIALOG_SEND_(3) operation spt_fork: Initiates a thread-aware fork() ...................................... spt_fork(2)

SPT_SERVERCLASS_DIALOG_BEGIN_: Initiates the dialog and also/ ........................................ SPT_SERVERCLASS_DIALOG_BEGIN_(3) function spt_accept: Initiates thread-aware accept( ) .................................... spt_accept(2) function spt_close: Initiates thread-aware close( ) ...................................... spt_close(2) function spt_connect: Initiates thread-aware connect( ) .................................. spt_connect(2) function spt_fclose: Initiates thread-aware fclose( ) ..................................... spt_fclose(2) function spt_fflush: Initiates thread-aware fflush( ) ...................................... spt_fflush(2) function spt_fgetc: Initiates thread-aware fgetc( ) ...................................... spt_fgetc(2) function spt_fgets: Initiates thread-aware fgets( ) ....................................... spt_fgets(2) function spt_fgetwc: Initiates thread-aware fgetwc( ) ................................... spt_fgetwc(2) function spt_fprintf: Initiates thread-aware fprintf( ) .................................... spt_fprintf(2) function spt_fputs: Initiates thread-aware fputs( ) ...................................... spt_fputs(2)

) function spt_putwchar: Initiates thread-aware fputwchar( ................................ spt_putwchar(2) function spt_fread: Initiates thread-aware fread( ) ...................................... spt_fread(2) for reading/ spt_RECEIVEREAD: Initiates thread-aware function .................................... spt_RECEIVEREAD(2) function spt_fwrite: Initiates thread-aware fwrite( ) ..................................... spt_fwrite(2) function spt_getc: Initiates thread-aware getc( ) ........................................ spt_getc(2) function spt_gets: Initiates thread-aware gets( ) ........................................ spt_gets(2) function spt_getw: Initiates thread-aware getw( ) ....................................... spt_getw(2) function spt_getwc: Initiates thread-aware getwc( ) ..................................... spt_getwc(2)

) function spt_getwchar: Initiates thread-aware getwchar( .................................. spt_getwchar(2) function spt_printf: Initiates thread-aware printf( ) ..................................... spt_printf(2)

527186-003 Hewlett-Packard Company Pindex

11

Pindex

12

OSS System Calls Reference Manual function spt_putc: Initiates thread-aware putc( ) ........................................ spt_putc(2) function spt_putchar: Initiates thread-aware putchar( ) .................................. spt_putchar(2) function. spt_puts: Initiates thread-aware puts( ) ........................................ spt_puts(2) function spt_putw: Initiates thread-aware putw( ) ...................................... spt_putw(2) function spt_putwc: Initiates thread-aware putwc( ) ..................................... spt_putwc(2) function spt_read: Initiates thread-aware read( ) ........................................ spt_read(2) function spt_readv: Initiates thread-aware readv( ) ...................................... spt_readv(2) function spt_recv: Initiates thread-aware recv( ) ........................................ spt_recv(2)

) function spt_recvfrom: Initiates thread-aware recvfrom( .................................. spt_recvfrom(2) function spt_recvmsg: Initiates thread-aware recvmsg(2) ................................ spt_recvmsg(2) procedure call spt_REPLYX: Initiates thread-aware REPLYX ................................... spt_REPLYX(2) function spt_select: Initiates thread-aware select( ) ..................................... spt_select(2) function spt_send: Initiates thread-aware send( ) ....................................... spt_send(2) function spt_sendmsg: Initiates thread-aware sendmsg( ) ................................ spt_sendmsg(2) function spt_sendto: Initiates thread-aware sendto( ) .................................... spt_sendto(2) function spt_system: Initiates thread-aware system( ) ................................... spt_system(2)

) function spt_vfprintf: Initiates thread-aware vfprintf( .................................... spt_vfprintf(2) function spt_vprintf: Initiates thread-aware vprintf( ) ................................... spt_vprintf(2) function spt_waitpid: Initiates thread-aware waitpid( ) .................................. spt_waitpid(2) function spt_write: Initiates thread-aware write( ) ...................................... spt_write(2)

Interrupts all threads awaiting input or output spt_interrupt: ...................................... spt_interrupt(2)

file descriptors for synchronous input/output multiplexing /among .............................. select(2)

of the dialog to the server instance in the Pathway/ /message .............................. SPT_SERVERCLASS_DIALOG_BEGIN_(3)

specified dialog to the server instance in the Pathway/ /the ....................................... SPT_SERVERCLASS_DIALOG_SEND_(3)

spt_setOSSFileIOHandler: Sets interest in file descriptor ............................................... spt_setOSSFileIOHandler(2)

tty: Is the general terminal interface .......................................................................... tty(7)

termios: Describes the terminal interface for POSIX compatibility ............................... termios(4) channel pipe: Creates an interprocess communication ......................................... pipe(2)

/variable; callable only from an interrupt-handler routine ............................................... pthread_cond_signal_int_np(2) input or output spt_interrupt: Interrupts all threads awaiting ...................................... spt_interrupt(2)

I/O spt_interruptTag: Interrupts thread awaiting tagged ................................ spt_interruptTag(2)

the thread for a specified time interval /Suspends execution of ................................... spt_sleep(2)

spt_awaitio: Awaits a tagged I/O file ............................................................................. spt_awaitio(2)

Interrupts thread awaiting tagged I/O spt_interruptTag: .................................................... spt_interruptTag(2)

Wakes up a thread awaiting tagged I/O spt_wakeup: ............................................................ spt_wakeup(2)

ioctl: Controls device files ............................................ ioctl(2)

Sets the process group ID for job control setpgid: ....................................................... setpgid(2)

a unique thread-speci fic data key /Generates ............................................................... pthread_key_create(2)

data associated with a key /Obtains the thread-speci fic .................................. pthread_getspecific(2)

Deletes a thread-speci fic data key pthread_key_delete: .............................................. pthread_key_delete(2)

data associated with a key /Sets the thread-speci fic ........................................ pthread_setspecific(2) or group of processes kill: Sends a signal to a process ................................... kill(2)

pthread_cond_signal: Unblocks at least one thread that is waiting/ ................................... pthread_cond_signal(2)

ftruncate: Changes file length .............................................................................. ftruncate(2)

pthread_getconcurrency: Gets level of concurrency ...................................................... pthread_getconcurrency(2)

pthread_setconcurrency: Sets level of concurrency ...................................................... pthread_setconcurrency(2)

ar: Describes the archive (library) file format ........................................................ ar(4)

limits: Specifies the system limits ............................................................................... limits(4)

ulimit: Sets and gets file size limits ............................................................................... ulimit(2)

float: Specifies the system limits for floating-point/ ............................................... float(4) limits limits: Specifies the system .......................................... limits(4)

/for socket connections and limits the backlog of incoming/ ................................... listen(2) directory entry for an existing/ link: Creates an additional ............................................ link(2)

information about a symbolic link or any file lstat: Provides ...................................... lstat(2)

Reads the value of a symbolic link readlink: ................................................................. readlink(2)

symlink: Creates a symbolic link to a file .................................................................... symlink(2)

getgroups: Gets the group list of the current process .............................................. getgroups(2) connections and limits the/ listen: Listens for socket ............................................... listen(2) and limits the backlog/ listen: Listens for socket connections ..................................... listen(2)

gethostname: Gets the name of the local host ........................................................................ gethostname(2)

getsockname: Gets the locally bound name of a socket .................................... getsockname(2) not wait if the/ /Attempts to lock a specified mutex but does ................................... pthread_mutex_trylock(2)

not wait if the mutex is already locked /specified mutex but does ................................. pthread_mutex_trylock(2)

pthread_mutex_lock: Locks an unlocked mutex ............................................. pthread_mutex_lock(2) threads pthread_lock_global_np: Locks the global mutex for ........................................... pthread_lock_global_np(2)

Hewlett-Packard Company 527186-003

Permuted Index

getlogin: Gets login name ...................................................................... getlogin(2) or write operation lseek: Sets file offset for read ........................................ lseek(2) a symbolic link or any file lstat: Provides information about ................................. lstat(2)

pthread_cleanup_push: (Macro) Establishes a/ ................................................... pthread_cleanup_push(2)

pthread_cleanup_pop: (Macro) Removes the/ ................................................... pthread_cleanup_pop(2)

/Registers the file descriptor to manage through a callback/ .......................................... spt_regOSSFileIOHandler(2)

tfile for concurrent transaction management /Initializes the ......................................... SPT_TMF_Init(2)

file number as one that the user manages /Unregisters a Guardian ................................ spt_unregFile(2)

a socket is at the out-of-band mark /Determines whether ........................................... sockatmark(2) deletion pthread_detach: Marks a thread object for .............................................. pthread_detach(2)

the calling thread’s signal mask /Examines or changes ......................................... pthread_sigmask(2)

Changes or examines the signal mask sigprocmask: ....................................................... sigprocmask(2)

value of the file mode creation mask umask: Sets and gets the ..................................... umask(2) constants math: Specifies the mathematical ................................ math(4)

math: Specifies the mathematical constants ................................................. math(4) policy /Returns the maximum priority for a scheduling ............................. sched_get_priority_max(2)

shmctl: Performs shared memory control operations ........................................... shmctl(2)

core: Is a file containing a memory image ............................................................... core(4)

saveabend: Is a file containing a memory image ............................................................... saveabend(4)

shmdt: Detaches a shared memory segment ........................................................... shmdt(2)

shmget: Creates a new shared memory segment or returns the/ ................................... shmget(2)

identifier of an existing shared memory segment /or returns the .................................. shmget(2) space/ shmat: Attaches a shared memory segment to the address ................................... shmat(2)

msgctl: Performs message control operations .......................................... msgctl(2)

recv: Receives a message from a connected socket ................................ recv(2)

msgrcv: Receives a message from a message queue .................................... msgrcv(2)

recvfrom: Receives a message from a socket .................................................. recvfrom(2) message/ recvmsg: Receives a message from a socket using a ..................................... recvmsg(2)

dialog and also sends the first message of the dialog to the/ /the ................................ SPT_SERVERCLASS_DIALOG_BEGIN_(3)

send: Sends a message on a connected socket .................................... send(2)

sendto: Sends a message on a socket ...................................................... sendto(2) message/ sendmsg: Sends a message on a socket using a ......................................... sendmsg(2)

msgrcv: Receives a message from a message queue ............................................................... msgrcv(2)

msgsnd: Sends a message to a message queue ............................................................... msgsnd(2)

or returns the identi fier for a message queue msgget: Creates .................................. msgget(2)

a message from a socket using a message structure /Receives ........................................ recvmsg(2)

a message on a socket using a message structure sendmsg: Sends .............................. sendmsg(2)

msgsnd: Sends a message to a message queue ......................................... msgsnd(2)

SPT_SERVERCLASS_SEND_: Sends a message to and receives a reply/ .................................. SPT_SERVERCLASS_SEND_(3)

thread for a specified number of microseconds /execution of the ................................... spt_usleep(2) policy /Returns the minimum priority for a scheduling .............................. sched_get_priority_min(2)

mkdir: Creates a directory ............................................ mkdir(2) a pathname to a character/ mknod: Creates a file or assigns ................................... mknod(2)

and gets the value of the file mode creation mask umask: Sets ................................. umask(2)

utime: Sets file access and modification times ......................................................... utime(2) to permanent/ fsync: Writes modified data and file attributes ................................... fsync(2) operations msgctl: Performs message control ............................... msgctl(2) identi fier for a message queue msgget: Creates or returns the ...................................... msgget(2) message queue msgrcv: Receives a message from a ............................. msgrcv(2) message queue msgsnd: Sends a message to a ...................................... msgsnd(2)

for synchronous input/output multiplexing /file descriptors ....................................... select(2)

pthread_mutex_destroy: Destroys a mutex .............................................................................. pthread_mutex_destroy(2)

pthread_mutex_init: Initializes a mutex .............................................................................. pthread_mutex_init(2)

pthread_mutex_unlock: Unlocks a mutex .............................................................................. pthread_mutex_unlock(2)

/Destroys a mutex attributes object ................................................. pthread_mutexattr_destroy(2)

/Initializes a mutex attributes object ................................................. pthread_mutexattr_init(2)

the mutex type attribute of a mutex attributes object /Obtains ................................. pthread_mutexattr_getkind_np(2)

the mutex type attribute of a mutex attributes object /Sets ........................................ pthread_mutexattr_setkind_np(2)

/Attempts to lock a specified mutex but does not wait if the/ ..................................... pthread_mutex_trylock(2)

/Locks the global mutex for threads ........................................................... pthread_lock_global_np(2)

/mutex but does not wait if the mutex is already locked ................................................ pthread_mutex_trylock(2)

Locks an unlocked mutex pthread_mutex_lock: ........................................ pthread_mutex_lock(2)

Unlocks the threads global mutex pthread_unlock_global_np: ............................. pthread_unlock_global_np(2) attributes object /Obtains the mutex type attribute of a mutex ................................... pthread_mutexattr_getkind_np(2) attributes object /Sets the mutex type attribute of a mutex ................................... pthread_mutexattr_setkind_np(2)

527186-003 Hewlett-Packard Company Pindex

13

Pindex

14

OSS System Calls Reference Manual

getlogin: Gets login name ............................................................................... getlogin(2)

Gets the locally bound name of a socket getsockname: ................................... getsockname(2)

gethostname: Gets the name of the local host ................................................... gethostname(2)

getpeername: Gets the name of the peer socket ................................................. getpeername(2) process /Gets the name of the transport-provider ..................................... socket_transport_name_get(2) process /Sets the name of the transport-provider ..................................... socket_transport_name_set(2)

bind: Binds a name to a socket ............................................................ bind(2)

Explain OSS file system file naming filename: .......................................................... filename(5)

Explains OSS file system path naming pathname: ........................................................ pathname(5) priority of the calling process nice: Changes the scheduling ....................................... nice(2)

null: Is a data sink file ................................................... null(7)

spt_regFile: Registers the file number ............................................................................ spt_regFile(2)

/Unregisters a Guardian file number as one that the user/ ......................................... spt_unregFile(2) transactions being used /Gets the number of concurrent TMF ........................................... spt_getTMFConcurrentTransactions(2) transactions /Sets the number of concurrent TMF ........................................... spt_setTMFConcurrentTransactions(2)

of the thread for a specified number of microseconds /execution ............................ spt_usleep(2)

Registers the file number spt_regFileIOHandler: .................................... spt_regFileIOHandler(2)

Registers the Pathsend file number spt_regPathsendFile: ....................................... spt_regPathsendFile(2)

/Destroys a mutex attributes object .............................................................................. pthread_mutexattr_destroy(2)

the specified thread attributes object /address attribute of ........................................... pthread_attr_getstackaddr(2)

a condition variable attributes object /Destroys ............................................................ pthread_condattr_destroy(2)

/Gets the attribute object for a thread .......................................................... pthread_getattr_np(2)

pthread_detach: Marks a thread object for deletion ......................................................... pthread_detach(2)

a condition variable attributes object /Initializes .......................................................... pthread_condattr_init(2)

attribute of a thread attributes object /Obtains the detachstate .................................... pthread_attr_getdetachstate(2)

attribute of a thread attributes object /Obtains the guardsize ...................................... pthread_attr_getguardsize_np(2)

attribute of a mutex attributes object /Obtains the mutex type .................................... pthread_mutexattr_getkind_np(2)

attribute of a thread attributes object /Obtains the stacksize ....................................... pthread_attr_getstacksize(2)

attribute of a thread attributes object /of the scheduling policy .................................. pthread_attr_getschedparam(2)

attribute of a thread attributes object /of the scheduling policy .................................. pthread_attr_setschedparam(2)

Destroys a thread attributes object pthread_attr_destroy: ........................................ pthread_attr_destroy(2)

Initializes a thread attributes object pthread_attr_init: ............................................... pthread_attr_init(2)

Initializes a mutex attributes object pthread_mutexattr_init: .................................... pthread_mutexattr_init(2)

attribute of a thread attributes object /Sets the detachstate .......................................... pthread_attr_setdetachstate(2)

attribute of a thread attributes object /Sets the guardsize ............................................. pthread_attr_setguardsize_np(2)

attribute of a mutex attributes object /Sets the mutex type .......................................... pthread_mutexattr_setkind_np(2)

attribute of a thread attributes object /Sets the stacksize .............................................. pthread_attr_setstacksize(2)

attribute of a thread attributes object /the inherit scheduling ...................................... pthread_attr_getinheritsched(2)

attribute of a thread attributes object /the inherit scheduling ...................................... pthread_attr_setinheritsched(2)

attribute of a thread attributes object /the scheduling policy ....................................... pthread_attr_getschedpolicy(2)

attribute of a thread attributes object /the scheduling policy ....................................... pthread_attr_setschedpolicy(2) policy/ pthread_getschedparam: Obtains the current scheduling ..................................... pthread_getschedparam(2) of/ pthread_attr_getdetachstate: Obtains the detachstate attribute .................................. pthread_attr_getdetachstate(2) of/ pthread_attr_getguardsize_np: Obtains the guardsize attribute .................................... pthread_attr_getguardsize_np(2)

pthread_attr_getinheritsched: Obtains the inherit scheduling/ .................................... pthread_attr_getinheritsched(2) of/ pthread_mutexattr_getkind_np: Obtains the mutex type attribute .................................. pthread_mutexattr_getkind_np(2) of/ pthread_attr_getschedparam: Obtains the scheduling parameters .............................. pthread_attr_getschedparam(2)

pthread_attr_getschedpolicy: Obtains the scheduling policy/ ..................................... pthread_attr_getschedpolicy(2)

pthread_attr_getstackaddr: Obtains the stackbase address/ ..................................... pthread_attr_getstackaddr(2) of a/ pthread_attr_getstacksize: Obtains the stacksize attribute ..................................... pthread_attr_getstacksize(2) the calling thread pthread_self: Obtains the thread identi fier of ..................................... pthread_self(2) associated/ pthread_getspecific: Obtains the thread-speci fic data ................................... pthread_getspecific(2)

ASCII/ ascii: Describes the octal, hexadecimal, and decimal .................................. ascii(5) operation lseek: Sets file offset for read or write ................................................... lseek(2)

/Calls a routine to be executed once by a single thread .................................................. pthread_once(2) or writing, creates a regular/ open: Opens a file for reading ..................................... open(2)

dup: Duplicates an open file descriptor ........................................................ dup(2)

dup2: Duplicates and controls an open file descriptor ........................................................ dup2(2)

fcntl: Controls open file descriptors ...................................................... fcntl(2)

Provides information about an open file fstat: ................................................................ fstat(2)

Gets fileset information for an open file fstatvfs: ........................................................... fstatvfs(2) writing, creates a regular/ open: Opens a file for reading or ............................................ open(2)

file offset for read or write operation lseek: Sets ..................................................... lseek(2)

about the last server-class send operation /Returns information ................................... SPT_SERVERCLASS_SEND_INFO_(3)

Initiates a thread-aware fork() operation spt_fork: ....................................................... spt_fork(2)

Hewlett-Packard Company 527186-003

527186-003

Permuted Index

msgctl: Performs message control operations ....................................................................... msgctl(2)

semop: Performs semaphore operations ....................................................................... semop(2)

system limits for floating-point operations float: Specifies the ...................................... float(4)

Performs semaphore control operations semctl: ......................................................... semctl(2)

Performs shared memory control operations shmctl: ......................................................... shmctl(2)

down socket send and receive operations shutdown: Shuts ......................................... shutdown(2)

cleanup-handler stack and optionally executes it /thread’s .................................... pthread_cleanup_pop(2)

getsockopt: Gets socket options ............................................................................ getsockopt(2)

setsockopt: Sets socket options ............................................................................ setsockopt(2)

/Creates a regular file in the OSS environment or rewrites an/ ................................. creat(2)

creates a regular file in the OSS environment /or writing, ...................................... open(2)

a directory entry from the OSS environment unlink: Removes ............................ unlink(2)

/Unregisters an OSS file descriptor ......................................................... spt_unregOSSFileIOHandler(2)

filename: Explain OSS file system file naming .......................................... filename(5)

hier: Explains the OSS file system hierarchy ............................................. hier(5)

pathname: Explains OSS file system path naming ........................................ pathname(5)

process group ID for a specified OSS process getpgid: Gets the ..................................... getpgid(2)

getpid: Gets the OSS process ID .............................................................. getpid(2)

getppid: Gets the parent OSS process ID .............................................................. getppid(2)

getpriority: Gets the OSS process scheduling priority .................................. getpriority(2)

/Renames a file or directory (OSS rename( ) function) .............................................. rename_oss(2)

whether a socket is at the out-of-band mark /Determines ..................................... sockatmark(2)

all threads awaiting input or output spt_interrupt: Interrupts ................................... spt_interrupt(2)

chown: Changes the owner and group IDs of a file ....................................... chown(2)

socketpair: Creates a pair of connected sockets .............................................. socketpair(2)

scheduling policy and scheduling parameters of a thread /current .................................... pthread_getschedparam(2)

scheduling policy and scheduling parameters of a thread /Sets the ................................... pthread_setschedparam(2) policy/ /Obtains the scheduling parameters of the scheduling ........................................ pthread_attr_getschedparam(2) policy/ /Sets the scheduling parameters of the scheduling ........................................ pthread_attr_setschedparam(2)

getppid: Gets the parent OSS process ID .................................................. getppid(2)

Explains OSS file system path naming pathname: ................................................ pathname(5)

execl: Executes a file using a pathname, a set of argument/ ........................................ execl(2)

execle: Executes a file using a pathname, a set of argument/ ........................................ execle(2)

execv: Executes a file using a pathname, an argv array, and/ ....................................... execv(2)

execve: Executes a file using a pathname, an argv array, and an/ .................................. execve(2) system path naming pathname: Explains OSS file ........................................ pathname(5)

Gets fileset information using a pathname statvfs: .......................................................... statvfs(2) file /Creates a file or assigns a pathname to a character special ................................... mknod(2)

/Registers the Pathsend file number ..................................................... spt_regPathsendFile(2)

/Registers the user-supplied Pathsend tag ................................................................... spt_regPathsendTagHandler(2)

/Unregisters the user-supplied Pathsend tag ................................................................... spt_unregPathsendTagHandler(2)

reply from a server process in a Pathway server class /receives a .................................. SPT_SERVERCLASS_SEND_(3)

to the server instance in the Pathway serverclass /dialog ......................................... SPT_SERVERCLASS_DIALOG_SEND_(3)

to the server instance in the Pathway serverclass /the dialog ................................... SPT_SERVERCLASS_DIALOG_BEGIN_(3)

getpeername: Gets the name of the peer socket ..................................................................... getpeername(2) the/ /Requests delivery of a pending cancelation request to ..................................... pthread_testcancel(2)

sigpending: Examines pending signals .............................................................. sigpending(2) operations msgctl: Performs message control ............................................. msgctl(2) operations semctl: Performs semaphore control ......................................... semctl(2)

semop: Performs semaphore operations ................................... semop(2) operations shmctl: Performs shared memory control ................................. shmctl(2)

data and file attributes to permanent storage /modified ........................................ fsync(2)

chmod: Changes file access permissions .................................................................... chmod(2) communication channel pipe: Creates an interprocess ........................................ pipe(2)

/Obtains the current scheduling policy and scheduling parameters/ .............................. pthread_getschedparam(2) of a thread /Sets the scheduling policy and scheduling parameters ................................ pthread_setschedparam(2)

/parameters of the scheduling policy attribute of a thread/ .......................................... pthread_attr_getschedparam(2)

/Obtains the scheduling policy attribute of a thread/ .......................................... pthread_attr_getschedpolicy(2)

/parameters of the scheduling policy attribute of a thread/ .......................................... pthread_attr_setschedparam(2) attributes/ /Sets the scheduling policy attribute of a thread ........................................... pthread_attr_setschedpolicy(2)

maximum priority for a scheduling policy /Returns the ........................................................ sched_get_priority_max(2)

minimum priority for a scheduling policy /Returns the ........................................................ sched_get_priority_min(2)

the terminal interface for POSIX compatibility /Describes ................................. termios(4)

Initiates thread-aware printf( ) function spt_printf: ......................................... spt_printf(2)

/Returns the maximum priority for a scheduling policy .................................... sched_get_priority_max(2)

Hewlett-Packard Company Pindex

15

Pindex

16

OSS System Calls Reference Manual

/Returns the minimum priority for a scheduling policy .................................... sched_get_priority_min(2)

Gets the OSS process scheduling priority getpriority: ....................................................... getpriority(2)

nice: Changes the scheduling priority of the calling process ....................................... nice(2)

Initiates thread-aware REPLYX procedure call spt_REPLYX: ....................................... spt_REPLYX(2)

_exit: Terminates a process ............................................................................ _exit(2)

fork: Creates a new process ............................................................................ fork(2)

/associated with the current process and current thread ............................................ SPT_ABORTTRANSACTION(3)

/associated with the current process and current thread ............................................ SPT_BEGINTRANSACTION(3)

/associated with the current process and current thread ............................................ SPT_ENDTRANSACTION(3)

/associated with the current process and current thread ............................................ SPT_RESUMETRANSACTION(3)

thread’s process forks a child process /called when the calling .................................. pthread_atfork(2)

priority of the calling process /Changes the scheduling ................................. nice(2)

/Contains the status of a process creation attempt ............................................... process_extension_results(5)

called when the calling thread’s process forks a child process /be ................................. pthread_atfork(2)

effective user ID of the current process geteuid: Gets the ............................................. geteuid(2)

the group list of the current process getgroups: Gets ................................................ getgroups(2)

process group ID of the calling process getpgrp: Gets the ............................................. getpgrp(2)

group ID for a specified OSS process /Gets the process ............................................. getpgid(2)

name of the transport-provider process /Gets the ........................................................... socket_transport_name_get(2)

the real user ID of the current process getuid: Gets the ............................................... getuid(2)

OSS process getpgid: Gets the process group ID for a specified ................................... getpgid(2)

setpgid: Sets the process group ID for job control .................................. setpgid(2) process getpgrp: Gets the process group ID of the calling .................................... getpgrp(2)

a new session and sets the process group ID setsid: Creates ................................. setsid(2)

getpid: Gets the OSS process ID ....................................................................... getpid(2)

getppid: Gets the parent OSS process ID ....................................................................... getppid(2)

/receives a reply from a server process in a Pathway server class ................................. SPT_SERVERCLASS_SEND_(3)

kill: Sends a signal to a process or group of processes ....................................... kill(2)

getpriority: Gets the OSS process scheduling priority ........................................... getpriority(2)

Sets the group ID of the calling process setgid: ............................................................... setgid(2)

name of the transport-provider process /Sets the ............................................................ socket_transport_name_set(2)

Sets the user ID of the calling process setuid: ............................................................... setuid(2)

the address space of the calling process /shared memory segment to ............................ shmat(2)

/Waits for a specific child process to stop or terminate .......................................... waitpid(2)

wait: Waits for any child process to terminate ...................................................... wait(2)

to another thread in the current process /to yield the processor ..................................... sched_yield(2)

tdm_fork: Creates a new process with HP extensions .......................................... tdm_fork(2)

tdm_spawn: Executes a new process with HP extensions .......................................... tdm_spawn(2)

tdm_spawnp: Executes a new process with HP extensions .......................................... tdm_spawnp(2)

a signal to a process or group of processes kill: Sends ..................................................... kill(2)

Contains the status of a process/ process_extension_results: ........................................... process_extension_results(5) the/ /a willingness to yield the processor to another thread in ...................................... sched_yield(2) symbolic link or any file lstat: Provides information about a ....................................... lstat(2)

stat: Provides information about a file ................................. stat(2) open file fstat: Provides information about an ..................................... fstat(2) fork-handler routines to be/ pthread_atfork: Declares ............................................... pthread_atfork(2) thread attributes object pthread_attr_destroy: Destroys a ................................. pthread_attr_destroy(2)

Obtains the detachstate/ pthread_attr_getdetachstate: ........................................ pthread_attr_getdetachstate(2)

Obtains the guardsize attribute/ pthread_attr_getguardsize_np: ..................................... pthread_attr_getguardsize_np(2)

Obtains the inherit scheduling/ pthread_attr_getinheritsched: ...................................... pthread_attr_getinheritsched(2)

Obtains the scheduling/ pthread_attr_getschedparam: ....................................... pthread_attr_getschedparam(2)

Obtains the scheduling policy/ pthread_attr_getschedpolicy: ....................................... pthread_attr_getschedpolicy(2)

Obtains the stackbase address/ pthread_attr_getstackaddr: ........................................... pthread_attr_getstackaddr(2)

Obtains the stacksize attribute/ pthread_attr_getstacksize: ............................................ pthread_attr_getstacksize(2) thread attributes object pthread_attr_init: Initializes a ...................................... pthread_attr_init(2) the detachstate attribute of a/ pthread_attr_setdetachstate: Sets ................................. pthread_attr_setdetachstate(2)

Sets the guardsize attribute of/ pthread_attr_setguardsize_np: ..................................... pthread_attr_setguardsize_np(2)

Sets the inherit scheduling/ pthread_attr_setinheritsched: ....................................... pthread_attr_setinheritsched(2) the scheduling parameters of the/ pthread_attr_setschedparam: Sets ................................ pthread_attr_setschedparam(2) the scheduling policy attribute/ pthread_attr_setschedpolicy: Sets ............................... pthread_attr_setschedpolicy(2) the stacksize attribute of a/ pthread_attr_setstacksize: Sets .................................... pthread_attr_setstacksize(2) thread terminate execution pthread_cancel: Requests that a ................................... pthread_cancel(2)

Removes the cleanup-handler/ pthread_cleanup_pop: (Macro) .................................... pthread_cleanup_pop(2)

Establishes a cleanup-handler/ pthread_cleanup_push: (Macro) .................................. pthread_cleanup_push(2)

Destroys a condition variable/ pthread_condattr_destroy: ............................................ pthread_condattr_destroy(2)

Hewlett-Packard Company 527186-003

Permuted Index

Initializes a condition variable/ pthread_condattr_init: .................................................. pthread_condattr_init(2) all threads that are waiting on/ pthread_cond_broadcast: Unblocks ............................. pthread_cond_broadcast(2) condition variable pthread_cond_destroy: Destroys a ............................... pthread_cond_destroy(2) condition variable pthread_cond_init: Initializes a ................................... pthread_cond_init(2) least one thread that is waiting/ pthread_cond_signal: Unblocks at .............................. pthread_cond_signal(2)

Unblocks one thread that is/ pthread_cond_signal_int_np: ....................................... pthread_cond_signal_int_np(2) thread to wait either for a/ pthread_cond_timedwait: Causes a ............................. pthread_cond_timedwait(2) thread to wait for the specified/ pthread_cond_wait: Causes a ....................................... pthread_cond_wait(2)

pthread_create: Creates a thread .................................. pthread_create(2) execution of a thread pthread_delay_np: Delays ............................................ pthread_delay_np(2) object for deletion pthread_detach: Marks a thread ................................... pthread_detach(2) thread identi fiers pthread_equal: Compares two ...................................... pthread_equal(2) calling thread pthread_exit: Terminates the ........................................ pthread_exit(2) attribute object for a thread pthread_getattr_np: Gets the ........................................ pthread_getattr_np(2) level of concurrency pthread_getconcurrency: Gets ...................................... pthread_getconcurrency(2)

Calculates an absolute/ pthread_get_expiration_np: ......................................... pthread_get_expiration_np(2) the current scheduling policy/ pthread_getschedparam: Obtains ................................. pthread_getschedparam(2) thread-speci fic data associated/ pthread_getspecific: Obtains the .................................. pthread_getspecific(2) thread to wait for the/ pthread_join: Causes the calling .................................. pthread_join(2) unique thread-speci fic data key pthread_key_create: Generates a ................................. pthread_key_create(2) thread-speci fic data key pthread_key_delete: Deletes a ..................................... pthread_key_delete(2) thread pthread_kill: Sends a signal to a .................................. pthread_kill(2) global mutex for threads pthread_lock_global_np: Locks the ............................ pthread_lock_global_np(2)

Destroys a mutex attributes/ pthread_mutexattr_destroy: ......................................... pthread_mutexattr_destroy(2)

Obtains the mutex type attribute/ pthread_mutexattr_getkind_np: ................................... pthread_mutexattr_getkind_np(2)

Initializes a mutex attributes/ pthread_mutexattr_init: ................................................ pthread_mutexattr_init(2)

Sets the mutex type attribute of/ pthread_mutexattr_setkind_np: ................................... pthread_mutexattr_setkind_np(2) mutex pthread_mutex_destroy: Destroys a ............................ pthread_mutex_destroy(2) mutex pthread_mutex_init: Initializes a ................................. pthread_mutex_init(2) unlocked mutex pthread_mutex_lock: Locks an .................................... pthread_mutex_lock(2) to lock a specified mutex but/ pthread_mutex_trylock: Attempts ............................... pthread_mutex_trylock(2) mutex pthread_mutex_unlock: Unlocks a .............................. pthread_mutex_unlock(2) be executed once by a single/ pthread_once: Calls a routine to .................................. pthread_once(2) identi fier of the calling thread pthread_self: Obtains the thread .................................. pthread_self(2) calling thread’s cancelability/ pthread_setcancelstate: Sets the ................................... pthread_setcancelstate(2) calling thread’s cancelability/ pthread_setcanceltype: Sets the ................................... pthread_setcanceltype(2) level of concurrency pthread_setconcurrency: Sets ....................................... pthread_setconcurrency(2) scheduling policy and scheduling/ pthread_setschedparam: Sets the ................................. pthread_setschedparam(2) thread-speci fic data associated/ pthread_setspecific: Sets the ......................................... pthread_setspecific(2) changes the calling thread’s/ pthread_sigmask: Examines or .................................... pthread_sigmask(2) delivery of a pending/ pthread_testcancel: Requests ....................................... pthread_testcancel(2) the threads global mutex pthread_unlock_global_np: Unlocks .......................... pthread_unlock_global_np(2)

spt_putc: Initiates thread-aware putc( ) function .............................................................. spt_putc(2)

Initiates thread-aware putchar( ) function spt_putchar: .................................. spt_putchar(2)

spt_puts: Initiates thread-aware puts( ) function. ............................................................. spt_puts(2)

spt_putw: Initiates thread-aware putw( ) function ............................................................. spt_putw(2)

spt_putwc: Initiates thread-aware putwc( ) function ........................................................... spt_putwc(2)

the identi fier for a message queue msgget: Creates or returns ................................ msgget(2)

Receives a message from a message queue msgrcv: ............................................................... msgrcv(2)

Sends a message to a message queue msgsnd: ............................................................... msgsnd(2)

spt_read: Initiates thread-aware read( ) function .............................................................. spt_read(2)

lseek: Sets file offset for read or write operation .................................................. lseek(2)

read: Reads from a file .................................................. read(2) regular/ open: Opens a file for reading or writing, creates a ......................................... open(2)

thread-aware function for reading $RECEIVE /Initiates ....................................... spt_RECEIVEREAD(2) symbolic link readlink: Reads the value of a ...................................... readlink(2)

spt_fd_read_ready: Waits on read-ready file descriptor .............................................. spt_fd_read_ready(2)

read: Reads from a file ............................................................ read(2) buffers readv: Reads from a file into scattered .................................... readv(2) link readlink: Reads the value of a symbolic ...................................... readlink(2)

spt_readv: Initiates thread-aware readv( ) function ............................................................ spt_readv(2) scattered buffers readv: Reads from a file into ......................................... readv(2)

getgid: Gets the real group ID .................................................................. getgid(2) process getuid: Gets the the real user ID of the current ............................................. getuid(2)

spt_INITRECEIVE: Registers $RECEIVE filename ...................................................... spt_INITRECEIVE(2)

527186-003 Hewlett-Packard Company Pindex

17

OSS System Calls Reference Manual

thread-aware function for reading $RECEIVE /Initiates .................................................... spt_RECEIVEREAD(2)

Shuts down socket send and receive operations shutdown: ...................................... shutdown(2) connected socket recv: Receives a message from a ........................................... recv(2) queue msgrcv: Receives a message from a message ............................ msgrcv(2)

recvfrom: Receives a message from a socket ............................... recvfrom(2) using a message/ recvmsg: Receives a message from a socket ............................... recvmsg(2) process/ /Sends a message to and receives a reply from a server ....................................... SPT_SERVERCLASS_SEND_(3)

spt_recv: Initiates thread-aware recv( ) function .............................................................. spt_recv(2) connected socket recv: Receives a message from a .................................. recv(2)

/Initiates thread-aware recvfrom( ) function ...................................................... spt_recvfrom(2) from a socket recvfrom: Receives a message ..................................... recvfrom(2) a socket using a message/ recvmsg: Receives a message from .............................. recvmsg(2)

Initiates thread-aware recvmsg(2) function spt_recvmsg: .............................. spt_recvmsg(2) callback/ spt_regTimerHandler: Registers a user-supplied timer .................................... spt_regTimerHandler(2)

spt_INITRECEIVE: Registers $RECEIVE filename ..................................... spt_INITRECEIVE(2) manage/ spt_regOSSFileIOHandler: Registers the file descriptor to ...................................... spt_regOSSFileIOHandler(2)

spt_regFile: Registers the file number .............................................. spt_regFile(2)

spt_regFileIOHandler: Registers the file number .............................................. spt_regFileIOHandler(2) number spt_regPathsendFile: Registers the Pathsend file ............................................ spt_regPathsendFile(2)

spt_regPathsendTagHandler: Registers the user-supplied/ ......................................... spt_regPathsendTagHandler(2) environment or/ creat: Creates a regular file in the OSS ................................................... creat(2)

for reading or writing, creates a regular file in the OSS/ /a file ....................................... open(2)

rmdir: Removes a directory ...................................................... rmdir(2) the OSS environment unlink: Removes a directory entry from ................................... unlink(2)

pthread_cleanup_pop: (Macro) Removes the cleanup-handler/ ..................................... pthread_cleanup_pop(2)

/Renames a file (Guardian rename( ) function) ........................................................ rename_guardian(2)

Renames a file or directory (OSS rename( ) function) rename_oss: ................................. rename_oss(2) directory rename: Renames a file or ............................................. rename(2)

(Guardian rename( ) function) rename_guardian: Renames a file ................................ rename_guardian(2) directory (OSS rename( )/ rename_oss: Renames a file or ..................................... rename_oss(2)

) function) rename_guardian: Renames a file (Guardian rename( ............................... rename_guardian(2)

rename: Renames a file or directory ........................................... rename(2) rename( ) function) rename_oss: Renames a file or directory (OSS ................................. rename_oss(2)

/Sends a message to and receives a reply from a server process in a/ .................................. SPT_SERVERCLASS_SEND_(3)

/Initiates thread-aware REPLYX procedure call ................................................ spt_REPLYX(2)

/delivery of a pending cancelation request to the calling thread ......................................... pthread_testcancel(2) cancelation/ pthread_testcancel: Requests delivery of a pending .................................... pthread_testcancel(2) execution pthread_cancel: Requests that a thread terminate .................................. pthread_cancel(2)

) /Executes callback type required by spt_regFileIOHandler( .............................. spt_FileIOHandler_p(2)

)/ /Executes callback type required by spt_regTimerHandler( ............................... spt_TimerHandler_p(2)

/Executes callback type required by the/ .............................................................. spt_OSSFileIOHandler_p(2) dialog after the/ /Cleans up resources for the specified ............................................. SPT_SERVERCLASS_DIALOG_END_(3) with the/ SPT_RESUMETRANSACTION: Restores a transaction associated ................................. SPT_RESUMETRANSACTION(3)

spt_generateTag: Increments and returns a static long tag ................................................. spt_generateTag(2) last/ SPT_SERVERCLASS_SEND_INFO_: Returns information about the ...................................... SPT_SERVERCLASS_SEND_INFO_(3)

errno: Returns the error condition value ................................. errno(5)

/Creates a new semaphore set ID or returns the ID of an existing/ ........................................ semget(2) message queue msgget: Creates or returns the identi fier for a ............................................. msgget(2)

/a new shared memory segment or returns the identi fier of an/ ........................................... shmget(2) a/ sched_get_priority_max: Returns the maximum priority for ............................... sched_get_priority_max(2) a/ sched_get_priority_min: Returns the minimum priority for ................................ sched_get_priority_min(2)

/file in the OSS environment or rewrites an existing file ................................................. creat(2)

rmdir: Removes a directory .......................................... rmdir(2)

chroot: Changes the effective root directory ................................................................. chroot(2)

/Removes the cleanup-handler routine from the calling thread’s/ ................................. pthread_cleanup_pop(2) single/ pthread_once: Calls a routine to be executed once by a .................................. pthread_once(2)

/Establishes a cleanup-handler routine to be executed when the/ ................................. pthread_cleanup_push(2)

only from an interrupt-handler routine /variable; callable ............................................ pthread_cond_signal_int_np(2) calling/ /Declares fork-handler routines to be called when the ...................................... pthread_atfork(2) memory image saveabend: Is a file containing a .................................. saveabend(4)

readv: Reads from a file into scattered buffers ............................................................. readv(2)

writev: Writes to a file from scattered buffers ............................................................. writev(2) the maximum priority for a/ sched_get_priority_max: Returns ................................ sched_get_priority_max(2) the minimum priority for a/ sched_get_priority_min: Returns ................................ sched_get_priority_min(2) attributes/ /Obtains the inherit scheduling attribute of a thread .................................... pthread_attr_getinheritsched(2)

Pindex

18 Hewlett-Packard Company 527186-003

Permuted Index attributes/ /Sets the inherit scheduling attribute of a thread .................................... pthread_attr_setinheritsched(2)

/the current scheduling policy and scheduling parameters of a thread ................................ pthread_getschedparam(2)

/Sets the scheduling policy and scheduling parameters of a thread ................................ pthread_setschedparam(2) scheduling policy/ /Obtains the scheduling parameters of the ........................................ pthread_attr_getschedparam(2) scheduling policy/ /Sets the scheduling parameters of the ........................................ pthread_attr_setschedparam(2) parameters/ /Obtains the current scheduling policy and scheduling ................................ pthread_getschedparam(2)

pthread_setschedparam: Sets the scheduling policy and scheduling/ .............................. pthread_setschedparam(2)

/the scheduling parameters of the scheduling policy attribute of a/ .................................. pthread_attr_getschedparam(2) thread attributes/ /Obtains the scheduling policy attribute of a .................................... pthread_attr_getschedpolicy(2)

/the scheduling parameters of the scheduling policy attribute of a/ .................................. pthread_attr_setschedparam(2) thread attributes/ /Sets the scheduling policy attribute of a .................................... pthread_attr_setschedpolicy(2)

the maximum priority for a scheduling policy /Returns .......................................... sched_get_priority_max(2)

the minimum priority for a scheduling policy /Returns .......................................... sched_get_priority_min(2)

getpriority: Gets the OSS process scheduling priority ........................................................ getpriority(2) calling/ nice: Changes the scheduling priority of the ............................................. nice(2) willingness to yield the/ sched_yield: Signals a ................................................... sched_yield(2)

shmdt: Detaches a shared memory segment .......................................................................... shmdt(2) of/ /Creates a new shared memory segment or returns the identi fier ................................... shmget(2)

of an existing shared memory segment /returns the identi fier ..................................... shmget(2)

shmat: Attaches a shared memory segment to the address space of/ .................................. shmat(2)

Initiates thread-aware select( ) function spt_select: ........................................ spt_select(2) descriptors for synchronous/ select: Selects among file .............................................. select(2) for synchronous/ select: Selects among file descriptors ...................................... select(2)

semctl: Performs semaphore control operations ...................................... semctl(2)

semop: Performs semaphore operations .................................................... semop(2)

ID of an/ semget: Creates a new semaphore set ID or returns the .................................... semget(2)

or returns the ID of an existing semaphore set /semaphore set ID ................................ semget(2) control operations semctl: Performs semaphore ......................................... semctl(2) set ID or returns the ID of an/ semget: Creates a new semaphore ................................ semget(2) operations semop: Performs semaphore ......................................... semop(2)

spt_send: Initiates thread-aware send( ) function .............................................................. spt_send(2)

shutdown: Shuts down socket send and receive operations .......................................... shutdown(2)

about the last server-class send operation /information ......................................... SPT_SERVERCLASS_SEND_INFO_(3) connected socket send: Sends a message on a .......................................... send(2) to the server/ /Initiates a send within the specified dialog ................................... SPT_SERVERCLASS_DIALOG_SEND_(3)

Initiates thread-aware sendmsg( ) function spt_sendmsg: .............................. spt_sendmsg(2) socket using a message structure sendmsg: Sends a message on a ................................... sendmsg(2) socket send: Sends a message on a connected .................................. send(2)

sendto: Sends a message on a socket ........................................ sendto(2) a message structure sendmsg: Sends a message on a socket using .............................. sendmsg(2) queue msgsnd: Sends a message to a message ...................................... msgsnd(2) reply/ SPT_SERVERCLASS_SEND_: Sends a message to and receives a ............................... SPT_SERVERCLASS_SEND_(3) group of processes kill: Sends a signal to a process or ....................................... kill(2)

pthread_kill: Sends a signal to a thread .............................................. pthread_kill(2)

/Initiates the dialog and also sends the first message of the/ ...................................... SPT_SERVERCLASS_DIALOG_BEGIN_(3)

Initiates thread-aware sendto( ) function spt_sendto: ..................................... spt_sendto(2) socket sendto: Sends a message on a ....................................... sendto(2)

a server process in a Pathway server class /a reply from .............................................. SPT_SERVERCLASS_SEND_(3)

the specified dialog after the server has ended it /for ................................................. SPT_SERVERCLASS_DIALOG_END_(3)

/the specified dialog to the server instance in the Pathway/ .................................... SPT_SERVERCLASS_DIALOG_SEND_(3)

/message of the dialog to the server instance in the Pathway/ .................................... SPT_SERVERCLASS_DIALOG_BEGIN_(3)

/to and receives a reply from a server process in a Pathway/ ......................................... SPT_SERVERCLASS_SEND_(3)

server instance in the Pathway serverclass /dialog to the .............................................. SPT_SERVERCLASS_DIALOG_SEND_(3)

server instance in the Pathway serverclass /of the dialog to the ................................... SPT_SERVERCLASS_DIALOG_BEGIN_(3)

/information about the last server-class send operation ........................................... SPT_SERVERCLASS_SEND_INFO_(3) group ID setsid: Creates a new session and sets the process .......................................... setsid(2)

semget: Creates a new semaphore set ID or returns the ID of an/ ....................................... semget(2)

/a file using a pathname, a set of argument strings, and/ ......................................... execl(2)

/a file using a filename, a set of argument strings, and/ ......................................... execlp(2)

/a file using a pathname, a set of argument strings, and an/ .................................... execle(2) for a/ sigsuspend: Changes the set of blocked signals and waits ................................... sigsuspend(2) file exec: Specifies a set of functions that execute a ...................................... exec(2)

the ID of an existing semaphore set /semaphore set ID or returns .................................. semget(2) calling process setgid: Sets the group ID of the .................................... setgid(2)

ID for job control setpgid: Sets the process group .................................... setpgid(2)

527186-003 Hewlett-Packard Company Pindex

19

Pindex

20

OSS System Calls Reference Manual

ulimit: Sets and gets file size limits .......................................... ulimit(2) file mode creation mask umask: Sets and gets the value of the ....................................... umask(2) times utime: Sets file access and modification .................................. utime(2) write operation lseek: Sets file offset for read or .............................................. lseek(2)

spt_setOSSFileIOHandler: Sets interest in file descriptor ....................................... spt_setOSSFileIOHandler(2)

pthread_setconcurrency: Sets level of concurrency .............................................. pthread_setconcurrency(2)

setsockopt: Sets socket options ........................................................ setsockopt(2)

pthread_setcancelstate: Sets the calling thread’s/ ............................................... pthread_setcancelstate(2)

pthread_setcanceltype: Sets the calling thread’s/ ............................................... pthread_setcanceltype(2) a/ pthread_attr_setdetachstate: Sets the detachstate attribute of ................................... pthread_attr_setdetachstate(2) process setgid: Sets the group ID of the calling .................................... setgid(2)

pthread_attr_setguardsize_np: Sets the guardsize attribute of a/ .................................. pthread_attr_setguardsize_np(2)

pthread_attr_setinheritsched: Sets the inherit scheduling/ .......................................... pthread_attr_setinheritsched(2) a/ pthread_mutexattr_setkind_np: Sets the mutex type attribute of ................................... pthread_mutexattr_setkind_np(2)

socket_transport_name_set: Sets the name of the/ ..................................................... socket_transport_name_set(2)

spt_setTMFConcurrentTransactions: Sets the number of concurrent TMF/ ........................... spt_setTMFConcurrentTransactions(2)

and decimal ASCII character sets /the octal, hexadecimal, ........................................ ascii(5)

setsid: Creates a new session and sets the process group ID .............................................. setsid(2) control setpgid: Sets the process group ID for job ................................. setpgid(2) the/ pthread_attr_setschedparam: Sets the scheduling parameters of ................................ pthread_attr_setschedparam(2)

pthread_attr_setschedpolicy: Sets the scheduling policy/ ........................................... pthread_attr_setschedpolicy(2)

pthread_setschedparam: Sets the scheduling policy and/ .................................... pthread_setschedparam(2)

pthread_attr_setstacksize: Sets the stacksize attribute of a/ ................................... pthread_attr_setstacksize(2) associated/ pthread_setspecific: Sets the thread-speci fic data ......................................... pthread_setspecific(2)

SPT_TMF_SetTxHandle: Sets the TMF transaction handle .................................. SPT_TMF_SetTxHandle(2) process setuid: Sets the user ID of the calling ...................................... setuid(2) sets the process group ID setsid: Creates a new session and ................................. setsid(2)

setsockopt: Sets socket options .................................... setsockopt(2) calling process setuid: Sets the user ID of the ....................................... setuid(2)

shmctl: Performs shared memory control operations ............................... shmctl(2)

shmdt: Detaches a shared memory segment ............................................... shmdt(2) the/ shmget: Creates a new shared memory segment or returns .............................. shmget(2)

the identi fier of an existing shared memory segment /or returns ............................ shmget(2) address space/ shmat: Attaches a shared memory segment to the ..................................... shmat(2) segment to the address space of/ shmat: Attaches a shared memory ............................... shmat(2) control operations shmctl: Performs shared memory ................................. shmctl(2) segment shmdt: Detaches a shared memory ............................... shmdt(2) memory segment or returns the/ shmget: Creates a new shared ....................................... shmget(2) and receive operations shutdown: Shuts down socket send ............................. shutdown(2) receive operations shutdown: Shuts down socket send and ......................................... shutdown(2) to take upon delivery of a/ sigaction: Specifies the action ...................................... sigaction(2)

blocked signals and waits for a signal /Changes the set of ............................................ sigsuspend(2) variables used by signal/ signal: Contains definitions and ................................... signal(4)

definitions and variables used by signal functions /Contains ........................................... signal(4)

or changes the calling thread’s signal mask /Examines ................................................. pthread_sigmask(2)

Changes or examines the signal mask sigprocmask: ............................................ sigprocmask(2)

action to take upon delivery of a signal sigaction: Specifies the ...................................... sigaction(2) processes kill: Sends a signal to a process or group of ...................................... kill(2)

pthread_kill: Sends a signal to a thread ........................................................... pthread_kill(2)

/for a condition variable to be signaled or broadcast, or for a/ ..................................... pthread_cond_timedwait(2)

condition variable to be signaled or broadcast /specified ................................... pthread_cond_wait(2)

sigpending: Examines pending signals ............................................................................. sigpending(2) the processor to/ sched_yield: Signals a willingness to yield ....................................... sched_yield(2)

/Changes the set of blocked signals and waits for a signal ........................................ sigsuspend(2) signals sigpending: Examines pending .................................... sigpending(2) the signal mask sigprocmask: Changes or examines ............................. sigprocmask(2) blocked signals and waits for a/ sigsuspend: Changes the set of ..................................... sigsuspend(2)

routine to be executed once by a single thread /Calls a .................................................... pthread_once(2)

null: Is a data sink file ........................................................................... null(7)

ulimit: Sets and gets file size limits ....................................................................... ulimit(2) socket is at the out-of-band/ sockatmark: Determines whether a .............................. sockatmark(2)

bind: Binds a name to a socket .............................................................................. bind(2)

connect: Connects a socket .............................................................................. connect(2)

sendto: Sends a message on a socket .............................................................................. sendto(2)

Accepts a new connection on a socket accept: ................................................................ accept(2)

Hewlett-Packard Company 527186-003

527186-003

Permuted Index backlog of/ listen: Listens for socket connections and limits the ................................ listen(2) communications socket: Creates an endpoint for .................................... socket(2)

Gets the name of the peer socket getpeername: ..................................................... getpeername(2)

Gets the locally bound name of a socket getsockname: ..................................................... getsockname(2)

sockatmark: Determines whether a socket is at the out-of-band mark ................................. sockatmark(2)

getsockopt: Gets socket options ................................................................ getsockopt(2)

setsockopt: Sets socket options ................................................................ setsockopt(2)

a message from a connected socket recv: Receives ................................................... recv(2)

Receives a message from a socket recvfrom: .......................................................... recvfrom(2) operations shutdown: Shuts down socket send and receive ................................................. shutdown(2)

Sends a message on a connected socket send: ................................................................... send(2)

/Receives a message from a socket using a message structure ................................. recvmsg(2)

sendmsg: Sends a message on a socket using a message structure ................................. sendmsg(2) connected sockets socketpair: Creates a pair of ........................................ socketpair(2)

Creates a pair of connected sockets socketpair: ....................................................... socketpair(2) the name of the/ socket_transport_name_get: Gets ................................ socket_transport_name_get(2) the name of the/ socket_transport_name_set: Sets ................................. socket_transport_name_set(2)

/memory segment to the address space of the calling process .......................................... shmat(2)

assigns a pathname to a character special file /Creates a file or ......................................... mknod(2) terminate waitpid: Waits for a specific child process to stop or ................................... waitpid(2)

signaled or broadcast, or for a specific expiration time /to be ..................................... pthread_cond_timedwait(2)

/one thread that is waiting on the specified condition variable .......................................... pthread_cond_signal(2)

/one thread that is waiting on the specified condition variable;/ ....................................... pthread_cond_signal_int_np(2)

threads that are waiting on the specified condition variable /all .................................. pthread_cond_broadcast(2)

/Causes a thread to wait for the specified condition variable to/ .................................... pthread_cond_wait(2)

/Aborts the specified dialog .............................................................. SPT_SERVERCLASS_DIALOG_ABORT_(3) has/ /Cleans up resources for the specified dialog after the server .................................... SPT_SERVERCLASS_DIALOG_END_(3)

/Initiates a send within the specified dialog to the server/ ....................................... SPT_SERVERCLASS_DIALOG_SEND_(3) if the mutex/ /Attempts to lock a specified mutex but does not wait ................................ pthread_mutex_trylock(2)

/execution of the thread for a specified number of microseconds ............................... spt_usleep(2)

Gets the process group ID for a specified OSS process getpgid: .................................... getpgid(2) object /address attribute of the specified thread attributes ............................................. pthread_attr_getstackaddr(2)

execution of the thread for a specified time interval /Suspends ................................ spt_sleep(2) execute a file exec: Specifies a set of functions that .................................... exec(2) delivery of a signal sigaction: Specifies the action to take upon .................................. sigaction(2) constants math: Specifies the mathematical ........................................... math(4)

limits: Specifies the system limits ............................................ limits(4) floating-point operations float: Specifies the system limits for ...................................... float(4) backs out a transaction/ SPT_ABORTTRANSACTION: Aborts and .............. SPT_ABORTTRANSACTION(3) thread-aware accept( ) function spt_accept: Initiates ...................................................... spt_accept(2) file spt_awaitio: Awaits a tagged I/O ................................. spt_awaitio(2) new transaction associated with/ SPT_BEGINTRANSACTION: Starts a ....................... SPT_BEGINTRANSACTION(3) close( ) function spt_close: Initiates thread-aware .................................. spt_close(2) thread-aware connect( ) function spt_connect: Initiates .................................................... spt_connect(2) transaction associated with the/ SPT_ENDTRANSACTION: Ends the ......................... SPT_ENDTRANSACTION(3) thread-aware fclose( ) function spt_fclose: Initiates ....................................................... spt_fclose(2) read-ready file descriptor spt_fd_read_ready: Waits on ........................................ spt_fd_read_ready(2) write-ready file descriptor spt_fd_write_ready: Waits on ...................................... spt_fd_write_ready(2) thread-aware fflush( ) function spt_fflush: Initiates ........................................................ spt_fflush(2) fgetc( ) function spt_fgetc: Initiates thread-aware .................................. spt_fgetc(2) fgets( ) function spt_fgets: Initiates thread-aware .................................. spt_fgets(2) thread-aware fgetwc( ) function spt_fgetwc: Initiates ...................................................... spt_fgetwc(2) callback type required by/ spt_FileIOHandler_p: Executes ................................... spt_FileIOHandler_p(2) thread-aware fork() operation spt_fork: Initiates a ....................................................... spt_fork(2) thread-aware fprintf( ) function spt_fprintf: Initiates ...................................................... spt_fprintf(2) function spt_fputc: Thread-aware fputc( ) .................................. spt_fputc(2) fputs( ) function spt_fputs: Initiates thread-aware .................................. spt_fputs(2)

) spt_fputwc: Thread-aware fputwc( .............................. spt_fputwc(2) fread( ) function spt_fread: Initiates thread-aware .................................. spt_fread(2) thread-aware fwrite( ) function spt_fwrite: Initiates ....................................................... spt_fwrite(2) returns a static long tag spt_generateTag: Increments and ................................. spt_generateTag(2) getc( ) function spt_getc: Initiates thread-aware ................................... spt_getc(2) thread-aware getchar( ) function spt_getchar: Executes ................................................... spt_getchar(2) gets( ) function spt_gets: Initiates thread-aware ................................... spt_gets(2)

Gets the number of concurrent/ spt_getTMFConcurrentTransactions: .......................... spt_getTMFConcurrentTransactions(2)

Hewlett-Packard Company Pindex

21

OSS System Calls Reference Manual getw( ) function spt_getw: Initiates thread-aware .................................. spt_getw(2) getwc( ) function spt_getwc: Initiates thread-aware ................................ spt_getwc(2) thread-aware getwchar( )/ spt_getwchar: Initiates .................................................. spt_getwchar(2) file spthread.h: Thread-aware header ................................. spthread.h(4)

$RECEIVE filename spt_INITRECEIVE: Registers ...................................... spt_INITRECEIVE(2) threads awaiting input or output spt_interrupt: Interrupts all ........................................... spt_interrupt(2) thread awaiting tagged I/O spt_interruptTag: Interrupts .......................................... spt_interruptTag(2) callback type required by the/ spt_OSSFileIOHandler_p: Executes ............................ spt_OSSFileIOHandler_p(2) thread-aware printf( ) function spt_printf: Initiates ........................................................ spt_printf(2) putc( ) function spt_putc: Initiates thread-aware ................................... spt_putc(2) thread-aware putchar( ) function spt_putchar: Initiates ..................................................... spt_putchar(2) puts( ) function. spt_puts: Initiates thread-aware ................................... spt_puts(2) putw( ) function spt_putw: Initiates thread-aware .................................. spt_putw(2) putwc( ) function spt_putwc: Initiates thread-aware ................................ spt_putwc(2) thread-aware fputwchar( )/ spt_putwchar: Initiates .................................................. spt_putwchar(2) read( ) function spt_read: Initiates thread-aware ................................... spt_read(2) readv( ) function spt_readv: Initiates thread-aware ................................. spt_readv(2) thread-aware function for/ spt_RECEIVEREAD: Initiates ..................................... spt_RECEIVEREAD(2) recv( ) function spt_recv: Initiates thread-aware ................................... spt_recv(2) thread-aware recvfrom( )/ spt_recvfrom: Initiates .................................................. spt_recvfrom(2) thread-aware recvmsg(2) function spt_recvmsg: Initiates ................................................... spt_recvmsg(2) number spt_regFile: Registers the file ....................................... spt_regFile(2)

callback type required by spt_regFileIOHandler( ) /Executes .............................. spt_FileIOHandler_p(2) the file number spt_regFileIOHandler: Registers ................................. spt_regFileIOHandler(2)

/callback type required by the spt_regOSSFileIOHandler( / ......................................... spt_OSSFileIOHandler_p(2)

Registers the file descriptor to/ spt_regOSSFileIOHandler: ........................................... spt_regOSSFileIOHandler(2) the Pathsend file number spt_regPathsendFile: Registers .................................... spt_regPathsendFile(2)

Registers the user-supplied/ spt_regPathsendTagHandler: ........................................ spt_regPathsendTagHandler(2)

/callback type required by spt_regTimerHandler( ) function ................................. spt_TimerHandler_p(2) user-supplied timer callback/ spt_regTimerHandler: Registers a ................................ spt_regTimerHandler(2) thread-aware REPLYX procedure/ spt_REPLYX: Initiates .................................................. spt_REPLYX(2) transaction associated with the/ SPT_RESUMETRANSACTION: Restores a .............. SPT_RESUMETRANSACTION(3) thread-aware select( ) function spt_select: Initiates ........................................................ spt_select(2) send( ) function spt_send: Initiates thread-aware ................................... spt_send(2) thread-aware sendmsg( ) function spt_sendmsg: Initiates ................................................... spt_sendmsg(2) thread-aware sendto( ) function spt_sendto: Initiates ...................................................... spt_sendto(2)

Aborts the specified dialog SPT_SERVERCLASS_DIALOG_ABORT_: ............. SPT_SERVERCLASS_DIALOG_ABORT_(3)

Initiates the dialog and also/ SPT_SERVERCLASS_DIALOG_BEGIN_: ............... SPT_SERVERCLASS_DIALOG_BEGIN_(3)

Cleans up resources for the/ SPT_SERVERCLASS_DIALOG_END_: ................... SPT_SERVERCLASS_DIALOG_END_(3)

Initiates a send within the/ SPT_SERVERCLASS_DIALOG_SEND_: ................. SPT_SERVERCLASS_DIALOG_SEND_(3) message to and receives a reply/ SPT_SERVERCLASS_SEND_: Sends a ..................... SPT_SERVERCLASS_SEND_(3)

Returns information about the/ SPT_SERVERCLASS_SEND_INFO_: ....................... SPT_SERVERCLASS_SEND_INFO_(3) interest in file descriptor spt_setOSSFileIOHandler: Sets ................................... spt_setOSSFileIOHandler(2)

Sets the number of concurrent/ spt_setTMFConcurrentTransactions: ........................... spt_setTMFConcurrentTransactions(2) the thread for a specified time/ spt_sleep: Suspends execution of ................................ spt_sleep(2) thread-aware system( ) function spt_system: Initiates ...................................................... spt_system(2) callback type required by/ spt_TimerHandler_p: Executes .................................... spt_TimerHandler_p(2) current TMF transaction handle SPT_TMF_GetTxHandle: Gets the .............................. SPT_TMF_GetTxHandle(2) tfile for concurrent transaction/ SPT_TMF_Init: Initializes the ..................................... SPT_TMF_Init(2) transaction handle SPT_TMF_SetTxHandle: Sets the TMF ...................... SPT_TMF_SetTxHandle(2)

Guardian file number as one that/ spt_unregFile: Unregisters a ......................................... spt_unregFile(2)

Unregisters an OSS file/ spt_unregOSSFileIOHandler: ...................................... spt_unregOSSFileIOHandler(2)

Unregisters the user-supplied/ spt_unregPathsendTagHandler: .................................... spt_unregPathsendTagHandler(2) the thread for a specified/ spt_usleep: Suspends execution of .............................. spt_usleep(2) thread-aware vfprintf( )/ spt_vfprintf: Initiates .................................................... spt_vfprintf(2) thread-aware vprintf( ) function spt_vprintf: Initiates ...................................................... spt_vprintf(2) thread-aware waitpid( ) function spt_waitpid: Initiates .................................................... spt_waitpid(2) awaiting tagged I/O spt_wakeup: Wakes up a thread ................................... spt_wakeup(2) write( ) function spt_write: Initiates thread-aware .................................. spt_write(2) writev( ) function spt_writev: Initiate thread-aware ................................. spt_writev(2)

/calling thread’s cleanup-handler stack and optionally executes it ................................... pthread_cleanup_pop(2) the specified thread/ /Obtains the stackbase address attribute of ....................................... pthread_attr_getstackaddr(2) attributes object /Obtains the stacksize attribute of a thread ....................................... pthread_attr_getstacksize(2) attributes object /Sets the stacksize attribute of a thread ....................................... pthread_attr_setstacksize(2) associated/ SPT_BEGINTRANSACTION: Starts a new transaction ................................................ SPT_BEGINTRANSACTION(3)

Pindex

22 Hewlett-Packard Company 527186-003

527186-003

Permuted Index a file stat: Provides information about .................................. stat(2)

Increments and returns a static long tag spt_generateTag: .................................. spt_generateTag(2) attempt /Contains the status of a process creation ........................................... process_extension_results(5) using a pathname statvfs: Gets fileset information ................................... statvfs(2)

for a specific child process to stop or terminate waitpid: Waits ................................. waitpid(2)

and file attributes to permanent storage /Writes modified data ...................................... fsync(2)

/a pathname, a set of argument strings, and an undeclared envp/ .................................. execle(2)

a pathname, a set of argument strings, and **environ /using ....................................... execl(2)

a filename, a set of argument strings, and **environ /using ....................................... execlp(2)

from a socket using a message structure /Receives a message ..................................... recvmsg(2)

on a socket using a message structure /Sends a message ........................................... sendmsg(2) for a specified time/ spt_sleep: Suspends execution of the thread ................................. spt_sleep(2) for a specified/ spt_usleep: Suspends execution of the thread ................................. spt_usleep(2)

readlink: Reads the value of a symbolic link ................................................................. readlink(2)

Provides information about a symbolic link or any file lstat: ..................................... lstat(2)

symlink: Creates a symbolic link to a file .................................................... symlink(2) to a file symlink: Creates a symbolic link ................................. symlink(2)

among file descriptors for synchronous input/output/ /Selects ............................. select(2)

Initiates thread-aware system( ) function spt_system: .................................... spt_system(2)

filename: Explain OSS file system file naming ......................................................... filename(5)

hier: Explains the OSS file system hierarchy ............................................................ hier(5)

limits: Specifies the system limits .................................................................. limits(4) operations float: Specifies the system limits for floating-point .................................... float(4)

pathname: Explains OSS file system path naming ....................................................... pathname(5)

identifying the current system uname: Gets information ................................. uname(2)

the user-supplied Pathsend tag /Registers ................................................................. spt_regPathsendTagHandler(2)

and returns a static long tag spt_generateTag: Increments ................................. spt_generateTag(2)

the user-supplied Pathsend tag /Unregisters ............................................................. spt_unregPathsendTagHandler(2)

spt_awaitio: Awaits a tagged I/O file ................................................................ spt_awaitio(2)

Interrupts thread awaiting tagged I/O spt_interruptTag: ........................................ spt_interruptTag(2)

Wakes up a thread awaiting tagged I/O spt_wakeup: ............................................... spt_wakeup(2)

tar: Describes the extended tar archive file format .................................................... tar(4) archive file format tar: Describes the extended tar ..................................... tar(4)

HP extensions tdm_execve: Executes a file with ................................. tdm_execve(2)

HP extensions tdm_execvep: Executes a file with ............................... tdm_execvep(2) with HP extensions tdm_fork: Creates a new process ................................. tdm_fork(2) with HP extensions tdm_spawn: Executes a new process ........................... tdm_spawn(2) process with HP extensions tdm_spawnp: Executes a new ....................................... tdm_spawnp(2) capability database termcap: Describes the terminal ................................... termcap(4)

termcap: Describes the terminal capability database ......................................... termcap(4)

tty: Is the general terminal interface .......................................................... tty(7)

termios: Describes the terminal interface for POSIX/ ...................................... termios(4)

/Requests that a thread terminate execution ....................................................... pthread_cancel(2)

Waits for any child process to terminate wait: .............................................................. wait(2)

specific child process to stop or terminate waitpid: Waits for a ..................................... waitpid(2)

_exit: Terminates a process ..................................................... _exit(2)

to be executed when the thread terminates /routine ........................................................ pthread_cleanup_push(2)

pthread_exit: Terminates the calling thread ....................................... pthread_exit(2)

calling thread to wait for the termination of a thread /the .......................................... pthread_join(2) interface for POSIX/ termios: Describes the terminal ................................... termios(4)

SPT_TMF_Init: Initializes the tfile for concurrent transaction/ .................................... SPT_TMF_Init(2)

pthread_create: Creates a thread .............................................................................. pthread_create(2)

pthread_kill: Sends a signal to a thread .............................................................................. pthread_kill(2)

the current process and current thread /associated with ................................................. SPT_ABORTTRANSACTION(3)

the current process and current thread /associated with ................................................. SPT_BEGINTRANSACTION(3)

the current process and current thread /associated with ................................................. SPT_ENDTRANSACTION(3)

the current process and current thread /associated with ................................................. SPT_RESUMETRANSACTION(3)

pthread_attr_destroy: Destroys a thread attributes object ................................................. pthread_attr_destroy(2)

pthread_attr_init: Initializes a thread attributes object ................................................. pthread_attr_init(2)

/Sets the guardsize attribute of a thread attributes object ................................................. pthread_attr_setguardsize_np(2)

/Sets the stacksize attribute of a thread attributes object ................................................. pthread_attr_setstacksize(2)

attribute of the specified thread attributes object /address .................................. pthread_attr_getstackaddr(2)

the detachstate attribute of a thread attributes object /Obtains ................................. pthread_attr_getdetachstate(2)

the guardsize attribute of a thread attributes object /Obtains ................................. pthread_attr_getguardsize_np(2)

the stacksize attribute of a thread attributes object /Obtains ................................. pthread_attr_getstacksize(2)

Hewlett-Packard Company Pindex

23

Pindex

24

OSS System Calls Reference Manual

scheduling policy attribute of a thread attributes object /of the ..................................... pthread_attr_getschedparam(2)

scheduling policy attribute of a thread attributes object /of the ..................................... pthread_attr_setschedparam(2)

the detachstate attribute of a thread attributes object /Sets ........................................ pthread_attr_setdetachstate(2)

inherit scheduling attribute of a thread attributes object /the ......................................... pthread_attr_getinheritsched(2)

scheduling policy attribute of a thread attributes object /the ......................................... pthread_attr_getschedpolicy(2)

inherit scheduling attribute of a thread attributes object /the ......................................... pthread_attr_setinheritsched(2)

scheduling policy attribute of a thread attributes object /the ......................................... pthread_attr_setschedpolicy(2)

spt_interruptTag: Interrupts thread awaiting tagged I/O ........................................... spt_interruptTag(2)

spt_wakeup: Wakes up a thread awaiting tagged I/O ........................................... spt_wakeup(2)

to be executed once by a single thread /Calls a routine .................................................. pthread_once(2)

to wait for the termination of a thread /Causes the calling thread ................................. pthread_join(2)

and scheduling parameters of a thread /current scheduling policy ................................ pthread_getschedparam(2)

/Suspends execution of the thread for a specified number of/ .................................. spt_usleep(2)

/Suspends execution of the thread for a specified time/ ........................................... spt_sleep(2) thread pthread_self: Obtains the thread identi fier of the calling ...................................... pthread_self(2)

pthread_equal: Compares two thread identi fiers ............................................................ pthread_equal(2)

/to yield the processor to another thread in the current process ......................................... sched_yield(2)

pthread_detach: Marks a thread object for deletion .............................................. pthread_detach(2)

request to the calling thread /of a pending cancelation .................................. pthread_testcancel(2)

Delays execution of a thread pthread_delay_np: ............................................. pthread_delay_np(2)

Terminates the calling thread pthread_exit: ...................................................... pthread_exit(2)

Gets the attribute object for a thread pthread_getattr_np: ........................................... pthread_getattr_np(2)

thread identi fier of the calling thread pthread_self: Obtains the .................................. pthread_self(2)

pthread_cancel: Requests that a thread terminate execution ........................................... pthread_cancel(2)

/routine to be executed when the thread terminates ........................................................... pthread_cleanup_push(2) specified/ /Unblocks at least one thread that is waiting on the ......................................... pthread_cond_signal(2) specified condition/ /Unblocks one thread that is waiting on the ......................................... pthread_cond_signal_int_np(2)

and scheduling parameters of a thread /the scheduling policy ....................................... pthread_setschedparam(2)

pthread_cond_timedwait: Causes a thread to wait either for a/ ............................................ pthread_cond_timedwait(2)

pthread_join: Causes the calling thread to wait for the/ .................................................... pthread_join(2)

pthread_cond_wait: Causes a thread to wait for the specified/ .................................... pthread_cond_wait(2)

spt_accept: Initiates thread-aware accept( ) function .................................... spt_accept(2)

spt_close: Initiates thread-aware close( ) function ...................................... spt_close(2)

spt_connect: Initiates thread-aware connect( ) function ................................. spt_connect(2)

spt_fclose: Initiates thread-aware fclose( ) function .................................... spt_fclose(2)

spt_fflush: Initiates thread-aware fflush( ) function ..................................... spt_fflush(2)

spt_fgetc: Initiates thread-aware fgetc( ) function ...................................... spt_fgetc(2)

spt_fgets: Initiates thread-aware fgets( ) function ...................................... spt_fgets(2)

spt_fgetwc: Initiates thread-aware fgetwc( ) function ................................... spt_fgetwc(2)

spt_fork: Initiates a thread-aware fork() operation ....................................... spt_fork(2)

spt_fprintf: Initiates thread-aware fprintf( ) function .................................... spt_fprintf(2)

spt_fputc: Thread-aware fputc( ) function ..................................... spt_fputc(2)

spt_fputs: Initiates thread-aware fputs( ) function ...................................... spt_fputs(2)

spt_fputwc: Thread-aware fputwc( ) ................................................. spt_fputwc(2) function spt_putwchar: Initiates thread-aware fputwchar( ) ............................................. spt_putwchar(2)

spt_fread: Initiates thread-aware fread( ) function ...................................... spt_fread(2)

spt_RECEIVEREAD: Initiates thread-aware function for reading/ .............................. spt_RECEIVEREAD(2)

spt_fwrite: Initiates thread-aware fwrite( ) function .................................... spt_fwrite(2)

spt_getc: Initiates thread-aware getc( ) function ....................................... spt_getc(2)

spt_getchar: Executes thread-aware getchar( ) function .................................. spt_getchar(2)

spt_gets: Initiates thread-aware gets( ) function ........................................ spt_gets(2)

spt_getw: Initiates thread-aware getw( ) function ...................................... spt_getw(2)

spt_getwc: Initiates thread-aware getwc( ) function .................................... spt_getwc(2)

spt_getwchar: Initiates thread-aware getwchar( ) function ............................... spt_getwchar(2)

spthread.h: Thread-aware header file ............................................... spthread.h(4)

spt_printf: Initiates thread-aware printf( ) function ..................................... spt_printf(2)

spt_putc: Initiates thread-aware putc( ) function ....................................... spt_putc(2)

spt_putchar: Initiates thread-aware putchar( ) function .................................. spt_putchar(2)

spt_puts: Initiates thread-aware puts( ) function. ...................................... spt_puts(2)

spt_putw: Initiates thread-aware putw( ) function ...................................... spt_putw(2)

spt_putwc: Initiates thread-aware putwc( ) function .................................... spt_putwc(2)

spt_read: Initiates thread-aware read( ) function ....................................... spt_read(2)

spt_readv: Initiates thread-aware readv( ) function ..................................... spt_readv(2)

spt_recv: Initiates thread-aware recv( ) function ....................................... spt_recv(2)

spt_recvfrom: Initiates thread-aware recvfrom( ) function ............................... spt_recvfrom(2)

Hewlett-Packard Company 527186-003

Permuted Index

spt_recvmsg: Initiates thread-aware recvmsg(2) function ............................... spt_recvmsg(2) call spt_REPLYX: Initiates thread-aware REPLYX procedure ................................ spt_REPLYX(2)

spt_select: Initiates thread-aware select( ) function ..................................... spt_select(2)

spt_send: Initiates thread-aware send( ) function ....................................... spt_send(2)

spt_sendmsg: Initiates thread-aware sendmsg( ) function ................................ spt_sendmsg(2)

spt_sendto: Initiates thread-aware sendto( ) function ................................... spt_sendto(2)

spt_system: Initiates thread-aware system( ) function ................................... spt_system(2)

spt_vfprintf: Initiates thread-aware vfprintf( ) function .................................. spt_vfprintf(2)

spt_vprintf: Initiates thread-aware vprintf( ) function ................................... spt_vprintf(2)

spt_waitpid: Initiates thread-aware waitpid( ) function .................................. spt_waitpid(2)

spt_write: Initiates thread-aware write( ) function ...................................... spt_write(2)

spt_writev: Initiate thread-aware writev( ) function .................................... spt_writev(2)

spt_interrupt: Interrupts all threads awaiting input or output .................................. spt_interrupt(2)

/Sets the calling thread’s cancelability state ........................................... pthread_setcancelstate(2)

/Sets the calling thread’s cancelability type ............................................ pthread_setcanceltype(2) and/ /routine from the calling thread’s cleanup-handler stack ..................................... pthread_cleanup_pop(2)

/Unlocks the threads global mutex ..................................................... pthread_unlock_global_np(2)

/to be called when the calling thread’s process forks a child/ ...................................... pthread_atfork(2)

Locks the global mutex for threads pthread_lock_global_np: ................................ pthread_lock_global_np(2)

/Examines or changes the calling thread’s signal mask ...................................................... pthread_sigmask(2) specified condition/ /Unblocks all threads that are waiting on the ..................................... pthread_cond_broadcast(2)

pthread_getspecific: Obtains the thread-specific data associated/ .................................... pthread_getspecific(2)

pthread_setspecific: Sets the thread-specific data associated/ .................................... pthread_setspecific(2)

/Generates a unique thread-specific data key ................................................ pthread_key_create(2)

pthread_key_delete: Deletes a thread-specific data key ................................................ pthread_key_delete(2)

/Registers a user-supplied timer callback function ................................................. spt_regTimerHandler(2)

Sets file access and modification times utime: ................................................................... utime(2)

/Gets the current TMF transaction handle ................................................ SPT_TMF_GetTxHandle(2)

SPT_TMF_SetTxHandle: Sets the TMF transaction handle ................................................ SPT_TMF_SetTxHandle(2)

/Sets the number of concurrent TMF transactions ........................................................... spt_setTMFConcurrentTransactions(2)

/Gets the number of concurrent TMF transactions being used ....................................... spt_getTMFConcurrentTransactions(2) current/ /Aborts and backs out a transaction associated with the .................................... SPT_ABORTTRANSACTION(3) current process and/ /Starts a new transaction associated with the .................................... SPT_BEGINTRANSACTION(3)

SPT_ENDTRANSACTION: Ends the transaction associated with the/ ................................... SPT_ENDTRANSACTION(3)

SPT_RESUMETRANSACTION: Restores a transaction associated with the/ ................................... SPT_RESUMETRANSACTION(3)

/Gets the current TMF transaction handle ......................................................... SPT_TMF_GetTxHandle(2)

SPT_TMF_SetTxHandle: Sets the TMF transaction handle ......................................................... SPT_TMF_SetTxHandle(2)

/the tfile for concurrent transaction management ............................................... SPT_TMF_Init(2)

/Sets the number of concurrent TMF transactions .................................................................... spt_setTMFConcurrentTransactions(2)

/Gets the number of concurrent TMF transactions being used ................................................. spt_getTMFConcurrentTransactions(2)

/Gets the name of the transport-provider process ............................................ socket_transport_name_get(2)

/Sets the name of the transport-provider process ............................................ socket_transport_name_set(2) interface tty: Is the general terminal ............................................ tty(7) attributes/ /Obtains the mutex type attribute of a mutex ............................................... pthread_mutexattr_getkind_np(2) attributes object /Sets the mutex type attribute of a mutex ............................................... pthread_mutexattr_setkind_np(2)

/Executes callback type required by/ ............................................................ spt_FileIOHandler_p(2)

/Executes callback type required by/ ............................................................ spt_TimerHandler_p(2)

/Executes callback type required by the/ ..................................................... spt_OSSFileIOHandler_p(2)

calling thread’s cancelability type /Sets the ................................................................. pthread_setcanceltype(2) limits ulimit: Sets and gets file size ........................................ ulimit(2) the file mode creation mask umask: Sets and gets the value of ................................ umask(2) identifying the current system uname: Gets information .............................................. uname(2) waiting/ pthread_cond_broadcast: Unblocks all threads that are ........................................ pthread_cond_broadcast(2) is waiting/ pthread_cond_signal: Unblocks at least one thread that ................................. pthread_cond_signal(2)

pthread_cond_signal_int_np: Unblocks one thread that is/ ......................................... pthread_cond_signal_int_np(2)

a set of argument strings, and an undeclared envp array /pathname, ............................... execle(2)

pthread_key_create: Generates a unique thread-speci fic data key .................................... pthread_key_create(2) from the OSS environment unlink: Removes a directory entry ............................... unlink(2)

pthread_mutex_lock: Locks an unlocked mutex ............................................................. pthread_mutex_lock(2)

pthread_mutex_unlock: Unlocks a mutex ............................................................ pthread_mutex_unlock(2)

pthread_unlock_global_np: Unlocks the threads global mutex ................................ pthread_unlock_global_np(2) number as one/ spt_unregFile: Unregisters a Guardian file ........................................... spt_unregFile(2)

spt_unregOSSFileIOHandler: Unregisters an OSS file/ ................................................ spt_unregOSSFileIOHandler(2)

spt_unregPathsendTagHandler: Unregisters the user-supplied/ ...................................... spt_unregPathsendTagHandler(2)

/Specifies the action to take upon delivery of a signal .............................................. sigaction(2)

527186-003 Hewlett-Packard Company Pindex

25

Pindex

26

OSS System Calls Reference Manual

environ: Contains the user environment ........................................................... environ(5)

setuid: Sets the user ID of the calling process ....................................... setuid(2)

geteuid: Gets the effective user ID of the current process ....................................... geteuid(2)

getuid: Gets the the real user ID of the current process ....................................... getuid(2)

file number as one that the user manages /a Guardian ............................................ spt_unregFile(2)

/Registers the user-supplied Pathsend tag ........................................... spt_regPathsendTagHandler(2)

/Unregisters the user-supplied Pathsend tag ........................................... spt_unregPathsendTagHandler(2)

spt_regTimerHandler: Registers a user-supplied timer callback/ ....................................... spt_regTimerHandler(2) argument/ execlp: Executes a file using a filename, a set of ............................................... execlp(2) and/ execvp: Executes a file using a filename, an argv array, .................................... execvp(2)

/Receives a message from a socket using a message structure ............................................. recvmsg(2)

/Sends a message on a socket using a message structure ............................................. sendmsg(2)

statvfs: Gets fileset information using a pathname ........................................................... statvfs(2) argument/ execl: Executes a file using a pathname, a set of ............................................. execl(2) argument/ execle: Executes a file using a pathname, a set of ............................................. execle(2) and/ execv: Executes a file using a pathname, an argv array, .................................. execv(2) and an/ execve: Executes a file using a pathname, an argv array, .................................. execve(2) modification times utime: Sets file access and ............................................ utime(2)

Returns the error condition value errno: .................................................................... errno(5)

readlink: Reads the value of a symbolic link ................................................ readlink(2) mask umask: Sets and gets the value of the file mode creation ..................................... umask(2)

/Destroys a condition variable attributes object .............................................. pthread_condattr_destroy(2)

/Initializes a condition variable attributes object .............................................. pthread_condattr_init(2)

/on the specified condition variable; callable only from an/ ................................... pthread_cond_signal_int_np(2)

Destroys a condition variable pthread_cond_destroy: .................................. pthread_cond_destroy(2)

Initializes a condition variable pthread_cond_init: ......................................... pthread_cond_init(2)

on the specified condition variable /that are waiting ............................................. pthread_cond_broadcast(2)

on the specified condition variable /thread that is waiting .................................... pthread_cond_signal(2)

/to wait either for a condition variable to be signaled or/ ............................................ pthread_cond_timedwait(2)

wait for the specified condition variable to be signaled or/ /to ...................................... pthread_cond_wait(2)

signal: Contains definitions and variables used by signal/ ............................................... signal(4)

/Initiates thread-aware vfprintf( ) function ......................................................... spt_vfprintf(2)

Initiates thread-aware vprintf( ) function spt_vprintf: .................................... spt_vprintf(2) variable to/ /Causes a thread to wait either for a condition ............................................ pthread_cond_timedwait(2) variable to/ /Causes a thread to wait for the specified condition .................................... pthread_cond_wait(2)

/Causes the calling thread to wait for the termination of a/ ........................................ pthread_join(2)

/a specified mutex but does not wait if the mutex is already/ ......................................... pthread_mutex_trylock(2) to terminate wait: Waits for any child process ................................. wait(2)

/Unblocks all threads that are waiting on the specified/ ............................................... pthread_cond_broadcast(2)

/at least one thread that is waiting on the specified/ ............................................... pthread_cond_signal(2)

/Unblocks one thread that is waiting on the specified/ ............................................... pthread_cond_signal_int_np(2)

Initiates thread-aware waitpid( ) function spt_waitpid: .................................. spt_waitpid(2) child process to stop or/ waitpid: Waits for a specific ......................................... waitpid(2)

the set of blocked signals and waits for a signal /Changes .......................................... sigsuspend(2) process to stop or/ waitpid: Waits for a specific child ............................................... waitpid(2) terminate wait: Waits for any child process to ...................................... wait(2) descriptor spt_fd_read_ready: Waits on read-ready file ................................................ spt_fd_read_ready(2) descriptor spt_fd_write_ready: Waits on write-ready file ............................................... spt_fd_write_ready(2)

I/O spt_wakeup: Wakes up a thread awaiting tagged ............................. spt_wakeup(2)

sockatmark: Determines whether a socket is at the/ ............................................. sockatmark(2) processor/ sched_yield: Signals a willingness to yield the ................................................. sched_yield(2) the server/ /Initiates a send within the specified dialog to ....................................... SPT_SERVERCLASS_DIALOG_SEND_(3)

chdir: Changes the current working directory .......................................................... chdir(2)

spt_write: Initiates thread-aware write( ) function ............................................................. spt_write(2)

Sets file offset for read or write operation lseek: ................................................... lseek(2)

write: Writes to a file ..................................................... write(2)

spt_fd_write_ready: Waits on write-ready file descriptor ............................................. spt_fd_write_ready(2) attributes to permanent/ fsync: Writes modified data and file ........................................ fsync(2)

write: Writes to a file ................................................................ write(2) buffers writev: Writes to a file from scattered ....................................... writev(2)

spt_writev: Initiate thread-aware writev( ) function ........................................................... spt_writev(2) scattered buffers writev: Writes to a file from .......................................... writev(2) in/ /Opens a file for reading or writing, creates a regular file ........................................ open(2) thread/ /Signals a willingness to yield the processor to another ...................................... sched_yield(2)

Hewlett-Packard Company 527186-003

Permuted Index

527186-003 Hewlett-Packard Company Pindex

27

A accept function, 1-2 to 1-4 access changing for a file, 1-14 determining for a file, 1-5 access function, 1-5 to 1-7 access modes, file, 1-38, 1-40, 3-2 ar file format, 11-2 ar header file, 11-2 archive file format cpio, 11-4 tar, 11-35 archive library file format, 11-2 arguments, passing, 2-3, 2-11, 2-19,

2-27, 2-35, 2-43, 8-3, 8-17,

8-42, 8-58

ASCII character set, 12-2 to 12-3 attributes, saving modified, 3-31

B bc utility, 11-14 binary file, executing, 2-4, 2-12, 2-20,

2-28, 2-36, 2-44, 8-4, 8-18,

8-42, 8-58 bind function, 1-8 to 1-10 binding, socket name, 1-8

C character set, ASCII, 12-2 chdir function, 1-11 to 1-13 child. See child process child process creating via fork, 3-9 creating via tdm_fork, 8-30 waiting for, 10-2, 10-7 chmod function, 1-14 to 1-17 chown function, 1-18 to 1-21 chroot function, 1-22 to 1-24 close function, 1-25 to 1-26 connect function, 1-27 to 1-30 connection accepting on a socket, 1-2 establishing between two sockets, 1-27 listening for on a socket, 4-9 control operations on a device file, 3-60 on a file, 1-38, 1-40, 3-2 on a message queue, 4-33 on semaphores, 7-10 on shared memory, 7-48 core file, 11-3 core memory image, 11-3 cpio archive file, 11-4 to 11-6 cpio file format, 11-4 to 11-6 creat function, 1-31 to 1-37 current working directory, changing,

1-11

527186-003 Hewlett-Packard Company Index

1

D data sink file, 11-18 decimal ASCII character set, 12-3 descriptors. See file descriptors device file, control operations on,

3-60 dir, format of directories, 11-7 dir file, 11-7 directory changing current working,

1-11 changing root, 1-22 creating, 4-22, 4-27 creating link, 4-5 effective root, 1-22 removing, 6-32 removing entry from, 9-7 renaming, 6-23, 6-26 drivers, for terminals, 11-57 dup function, 1-38 to 1-39 dup2 function, 1-40 to 1-41

Index

2

E environ external variable, 12-4 to

12-20 environment, specifying, 2-12, 2-20,

2-28, 2-36, 2-44, 8-3, 8-18,

8-42, 8-58 environment variables

_RLD_FIRST_LIB_PATH,

12-14

_RLD_LIB_PATH, 12-14

AS1, 12-4

CACHE_CDS_SERVER,

12-4

CACHE_CDS_SERVER_IP,

12-4

CCOMBE, 12-4

CDPATH, 12-4

CDS_ADVERTISEMENTS,

12-4

CDSD_DATABASE_DIR,

12-4

CELL_ADMIN, 12-4

Hewlett-Packard Company

OSS System Calls Reference Manual

CELL_ADMIN_PW, 12-5

CELL_NAME, 12-5

CFE, 12-5 check_time, 12-5

CLONE_FROM, 12-5

CLONING_REQUIRED,

12-5

COMP_ROOT, 12-5

COPY_CONFIG_HOST,

12-5

COPY_CONFIG_INFO,

12-6

CPU_LIST, 12-6

CRON_NAMED, 12-6

DATEMSK, 12-6

DCE_PRIVUSER, 12-6

DCE_PROCESS_PREFIX,

12-6

DCE_SCP_PROCESS_NAME,

12-6

DCE_SOCKET_REUSE,

12-7

DCED_ADMIN, 12-7

DCEVH, 12-7

DIR_REPLICATE, 12-7

DISPLAY_THRESHOLD,

12-8

DO_CHECKS, 12-8

DTS_CONFIG, 12-8

ECOBFE, 12-8

EDITOR, 12-8

ELD, 12-8

EMS_COLLECTOR, 12-8

ENV, 12-9

EXINIT, 12-9

EXIT_ON_ERROR, 12-9

FCEDIT, 12-9

FPATH, 12-9

Guardian PARAMs, 12-9

HISTFILE, 12-9

HISTSIZE, 12-9

HOME, 12-9

HOST_NAME_IP, 12-9

IFS, 12-9, 12-20

JAVA_HOME, 12-9

KEYSEED, 12-9

LAN_NAME, 12-10

LANG, 12-9

LC_ALL, 12-10

527186-003

Index

527186-003

LC_COLLATE, 12-10

LC_CTYPE, 12-10

LC_MESSAGES, 12-10

LC_MONETARY, 12-11

LC_NUMERIC, 12-11

LC_TIME, 12-11

LD, 12-11

LOCPATH, 12-11

LOG_THRESHOLD, 12-11

LOGNAME, 12-11

MAKEFLAGS, 12-11

MANPATH, 12-11

MSGVERB, 12-11

MULTIPLE_LAN, 12-11

MXCMP, 12-12

MXCMPUM, 12-12

MXSQLC, 12-12

MXSQLCO, 12-12

NLD, 12-12

NLSPATH, 12-12

PATH, 12-12

PMSEARCHLIST, 12-12

PRINTER, 12-12

PS1, 12-13, 12-20

PS2, 12-13, 12-20

PS3, 12-13

PS4, 12-13

PWD, 12-13

PWD_MGMT_SVR, 12-13

PWD_MGMT_SVR_OPTIONS,

12-13

REMOVE_PREV_CONFIG,

12-13

REMOVE_PREV_INSTALL,

12-13

REP_CLEARINGHOUSE,

12-13

REPLICATE_ALL_DIRS,

12-14

REPLICATE_DIR_LIST,

12-14

SEC_REPLICA, 12-14

SEC_SERVER, 12-14

SHELL, 12-14

SOCKET_TRANSPORT_NAME,

12-14

SQLCFE, 12-14

SQLCOMP, 12-14

SQLMX_PREPROCESSOR_VERSION,

12-15

SWAPVOL, 12-15

SYNC_CLOCKS, 12-15

TANDEM_ALT_SRL, 12-15

TANDEM_INSTALL_DIR,

12-15

TCPIP_PROCESS_NAME,

12-15

TCPIP_RESOLVER_NAME,

12-16

TERM, 12-16

TERMCAP, 12-16

TERMINFO, 12-16

TERMPATH, 12-16

TIME_SERVER, 12-17

TMOUT, 12-17

TMPDIR, 12-17

TOLERANCE_SEC, 12-17

TOTAL_CLERKS, 12-17

TZ, 12-17

UGEN, 12-18

UNCONFIG_HOST_PRESET,

12-18

UOPT, 12-18

UPDATE_ALL_CLONES,

12-18

UPDATE_DEFAULT_LIBDCESO,

12-19

USE_DEF_MSG_PATH,

12-19

USER, 12-19

UTILSGE, 12-19

VISUAL, 12-19

ZCPU, 12-19 errno external variable, 12-21 to

12-28 errno value

[E2BIG], 2-8, 2-16, 2-24,

2-32, 2-40, 2-48,

4-41, 7-20, 8-13,

8-27, 8-53, 8-69,

12-21

[EACCES], 1-6, 1-8, 1-12,

1-16, 1-19, 1-23,

1-28, 1-34, 2-8, 2-16,

2-24, 2-32, 2-40,

2-48, 3-12, 4-6, 4-20,

4-24, 4-30, 4-34,

4-38, 4-41, 4-43,

5-10, 6-7, 6-28, 6-33,

7-13, 7-16, 7-20,

7-26, 7-30, 7-34,

Hewlett-Packard Company Index

3

Index

4

OSS System Calls Reference Manual

7-46, 7-49, 7-56,

7-73, 7-77, 7-167,

7-177, 7-180, 8-13,

8-27, 8-39, 8-53,

8-69, 9-8, 9-12,

12-21

[EADDRINUSE], 1-8, 1-28,

12-21

[EADDRNOTAVAIL], 1-9,

1-28, 12-21

[EAFNOSUPPORT], 1-9,

1-28, 7-26, 7-30,

7-73, 7-77, 12-21

[EAGAIN], 2-8, 2-16, 2-24,

2-32, 2-40, 2-49, 3-6,

3-12, 4-43, 6-4, 6-11,

7-20, 8-14, 8-28,

8-39, 8-53, 8-70,

10-15, 10-20, 12-21

[EALREADY], 1-28, 12-21

[EBADCF], 12-21

[EBADDATA], 12-21

[EBADF], 1-3, 1-9, 1-25,

1-28, 1-38, 1-41, 3-6,

3-21, 3-29, 3-31,

3-33, 3-41, 3-49,

3-55, 3-62, 4-9, 4-11,

6-4, 6-11, 6-14, 6-17,

6-20, 7-8, 7-23, 7-26,

7-30, 7-42, 7-58,

7-69, 8-53, 8-70,

10-15, 10-20, 12-21

[EBADFILE], 12-21

[EBADMSG], 12-21

[EBADSYS], 12-21

[EBIGDIR], 12-22

[EBUSY], 6-28, 6-33, 9-8,

12-22

[ECHILD], 10-6, 10-11,

12-22

[ECONNABORTED], 1-3,

12-22

[ECONNREFUSED], 1-28,

12-22

[ECONNRESET], 1-3, 1-9,

1-28, 3-6, 3-41, 3-50,

3-55, 4-9, 6-4, 6-11,

6-14, 6-17, 6-21,

7-23, 7-26, 7-30,

7-42, 7-58, 7-69,

10-15, 10-20, 12-22

Hewlett-Packard Company

[ECWDTOOLONG], 12-22

[EDEADLK], 12-22

[EDEFINEERR], 7-73, 7-80,

12-22

[EDESTADDRREQ], 1-9,

4-10, 7-23, 7-27,

7-30, 12-22

[EDOM], 12-22

[EEXIST], 4-6, 4-24, 4-30,

4-38, 5-10, 6-29,

7-17, 7-56, 7-180,

12-22

[EFAULT], 1-3, 1-6, 1-9,

1-12, 1-16, 1-19,

1-23, 1-29, 1-34, 2-8,

2-17, 2-25, 2-32,

2-40, 2-49, 3-6, 3-21,

3-29, 3-38, 3-42,

3-50, 3-55, 3-58,

3-62, 4-6, 4-20, 4-24,

4-30, 4-34, 4-38,

4-41, 4-43, 5-10,

5-14, 6-4, 6-7, 6-11,

6-14, 6-17, 6-21,

6-29, 6-33, 7-13,

7-20, 7-23, 7-27,

7-30, 7-43, 7-49,

7-62, 7-64, 7-66,

7-77, 7-80, 7-82,

7-167, 7-177, 7-180,

8-14, 8-28, 8-39,

8-53, 8-70, 9-6, 9-8,

9-12, 10-6, 10-11,

10-15, 10-20, 12-22

[EFBIG], 3-33, 7-20, 10-15,

10-20, 12-22

[EFILEBAD], 1-34, 5-10,

6-4, 6-11, 12-23

[EFSBAD], 1-6, 1-12, 1-16,

1-19, 1-23, 1-34,

3-21, 4-6, 4-20, 4-24,

4-30, 5-10, 6-7, 6-29,

6-34, 7-167, 7-180,

9-8, 9-12, 12-23

[EFSERR], 12-23

[EGUARDIANLOCKED],

10-15, 10-20, 12-23

[EGUARDIANOPEN], 1-34,

5-10, 6-29, 9-8,

12-23

527186-003

Index

527186-003

[EHAVEOOB], 12-23

[EHLDSEM], 8-14, 8-28,

8-39, 8-53, 8-70,

12-23

[EHOSTDOWN], 12-23

[EHOSTUNREACH], 1-29,

7-30, 12-23

[EIDRM], 4-41, 4-43, 7-20,

12-23

[EILSEQ], 12-23

[EINPROGRESS], 1-29,

12-23

[EINTR], 1-3, 1-6, 1-29,

1-35, 3-6, 3-29, 3-31,

3-33, 3-62, 4-41,

4-43, 5-10, 6-4, 6-11,

6-14, 6-17, 6-21, 7-8,

7-20, 7-23, 7-27,

7-31, 7-67, 7-177,

10-6, 10-12, 10-15,

10-20, 12-23

[EINVAL], 1-3, 1-6, 1-9,

1-16, 1-19, 1-23,

1-29, 1-35, 2-8, 2-17,

2-25, 2-32, 2-41,

2-49, 3-6, 3-29, 3-31,

3-33, 3-38, 3-42,

3-43, 3-47, 3-50,

3-55, 3-62, 4-4, 4-6,

4-10, 4-12, 4-24,

4-30, 4-34, 4-38,

4-41, 4-44, 5-10, 6-4,

6-7, 6-11, 6-14, 6-17,

6-21, 6-29, 6-34, 7-8,

7-13, 7-17, 7-21,

7-27, 7-31, 7-33,

7-34, 7-43, 7-44,

7-47, 7-50, 7-52,

7-56, 7-58, 7-62,

7-66, 7-80, 7-82,

8-14, 8-28, 8-39,

8-53, 8-70, 9-8, 9-12,

10-12, 10-15, 10-20,

12-24

[EIO], 1-6, 1-9, 1-12, 1-25,

1-29, 1-35, 3-12,

3-29, 3-31, 3-34, 4-6,

4-20, 4-24, 4-30,

5-11, 6-4, 6-7, 6-11,

6-17, 6-21, 6-34,

7-23, 7-27, 7-31,

Hewlett-Packard Company

7-167, 7-177, 7-180,

8-14, 8-28, 8-39,

8-53, 8-70, 9-8, 9-12,

10-15, 10-21, 12-24

[EISCONN], 1-29, 12-24

[EISDIR], 1-35, 4-12, 5-11,

6-4, 6-11, 6-29,

12-24

[EISGUARDIAN], 1-25,

1-39, 1-41, 3-7, 3-21,

3-30, 3-31, 3-34,

4-12, 6-4, 6-11,

10-16, 10-21, 12-24

[ELOOP], 1-6, 1-9, 1-12,

1-16, 1-19, 1-23,

1-29, 1-35, 2-8, 2-17,

2-25, 2-32, 2-41,

2-49, 4-6, 4-20, 4-24,

4-30, 5-11, 6-7, 6-29,

6-34, 7-27, 7-31,

7-167, 7-177, 7-180,

8-14, 8-28, 8-54,

8-70, 9-8, 9-12,

12-24

[EMFILE], 1-3, 1-35, 1-39,

2-8, 2-17, 2-25, 2-32,

2-41, 2-49, 3-7, 5-11,

5-15, 6-21, 7-47,

7-73, 7-77, 8-14,

8-28, 8-54, 8-70,

12-24

[EMLINK], 4-6, 12-24

[EMSGQNOTRUNNING],

4-35, 4-38, 4-41,

4-44, 12-24

[EMSGSIZE], 7-23, 7-27,

7-31, 12-24

[ENAMETOOLONG], 1-6,

1-9, 1-12, 1-16, 1-19,

1-23, 1-35, 2-8, 2-17,

2-25, 2-32, 2-41,

2-49, 4-6, 4-20, 4-24,

4-30, 5-11, 6-7, 6-29,

6-34, 7-27, 7-167,

7-177, 7-180, 8-14,

8-28, 8-54, 8-70, 9-8,

9-12, 12-24

[ENETDOWN], 1-29, 3-7,

3-21, 3-30, 3-31,

3-34, 3-62, 5-11, 6-4,

6-12, 7-8, 7-23, 7-31,

Index

5

Index

6

OSS System Calls Reference Manual

10-16, 10-21, 12-24

[ENETRESET], 12-24

[ENETUNREACH], 1-29,

7-31, 12-25

[ENFILE], 1-3, 5-11, 7-73,

7-77, 12-25

[ENOBUFS], 1-3, 1-10, 1-29,

3-42, 3-50, 3-55,

4-10, 6-14, 6-17,

6-21, 7-23, 7-27,

7-31, 7-43, 7-58,

7-69, 7-73, 7-77,

12-25

[ENOCPU], 8-14, 8-28, 8-54,

8-70, 12-25

[ENOCRE], 12-25

[ENODATA], 12-25

[ENODEV], 2-9, 2-17, 2-25,

2-33, 2-41, 2-49,

8-14, 8-28, 8-54,

8-70, 12-25

[ENOENT], 1-7, 1-9, 1-12,

1-17, 1-19, 1-24,

1-29, 1-35, 2-9, 2-17,

2-25, 2-33, 2-41,

2-49, 4-7, 4-21, 4-24,

4-30, 4-38, 5-11, 6-7,

6-29, 6-34, 7-17,

7-27, 7-31, 7-56,

7-73, 7-77, 7-167,

7-177, 7-180, 8-15,

8-29, 8-54, 8-71, 9-9,

9-13, 12-25

[ENOERR], 12-25

[ENOEXEC], 2-9, 2-17,

2-25, 2-33, 2-41,

2-49, 8-15, 8-29,

8-54, 8-71, 12-25

[ENOIMEM], 12-25

[ENOLCK], 3-7, 12-25

[ENOMEM], 1-3, 1-10, 1-30,

1-36, 2-9, 2-17, 2-25,

2-33, 2-41, 2-49,

3-12, 3-42, 3-50,

3-55, 4-10, 5-12,

5-15, 6-14, 6-17,

6-21, 6-30, 7-23,

7-28, 7-31, 7-43,

7-47, 7-56, 7-59,

7-69, 7-74, 7-77,

8-15, 8-29, 8-39,

Hewlett-Packard Company

8-54, 8-71, 12-25

[ENOMSG], 4-41, 12-25

[ENONSTOP], 12-25

[ENOPROTOOPT], 3-55,

7-28, 7-43, 12-25

[ENOREPLY], 12-25

[ENOROOT], 1-7, 1-12,

1-17, 1-20, 1-24,

1-36, 3-21, 4-7, 4-21,

4-25, 4-31, 5-12,

5-15, 6-7, 6-30, 6-34,

7-167, 7-181, 9-9,

9-13, 12-25

[ENOSPC], 1-36, 4-7, 4-25,

4-31, 4-38, 5-12,

6-30, 7-17, 7-21,

7-56, 7-181, 10-16,

10-21, 12-26

[ENOSYS], 12-26

[ENOTCONN], 3-42, 6-4,

6-12, 6-14, 6-17,

6-21, 7-23, 7-28,

7-31, 7-59, 10-16,

10-21, 12-26

[ENOTDIR], 1-7, 1-10, 1-13,

1-17, 1-20, 1-24,

1-30, 1-36, 2-9, 2-17,

2-33, 2-41, 2-49, 4-7,

4-21, 4-25, 4-31,

5-12, 6-7, 6-30, 6-34,

7-28, 7-31, 7-168,

7-177, 7-181, 8-15,

8-29, 8-54, 8-71, 9-9,

9-13, 12-26

[ENOTEMPTY], 6-34, 12-26

[ENOTOSS], 2-9, 2-17, 2-25,

2-33, 2-41, 2-49, 3-7,

3-12, 3-43, 3-48,

3-58, 4-4, 4-35, 4-38,

4-41, 4-44, 7-13,

7-17, 7-21, 7-34,

7-36, 7-47, 7-50,

7-52, 7-56, 7-62,

7-64, 7-66, 7-67,

8-15, 8-29, 8-39,

8-54, 8-71, 10-6,

10-12, 12-26

[ENOTSOCK], 1-3, 1-10,

1-30, 3-42, 3-50,

3-55, 4-10, 6-14,

6-18, 6-21, 7-23,

527186-003

527186-003

7-28, 7-31, 7-43,

7-59, 12-26

[ENOTSUP], 3-63, 7-8,

7-181, 12-26

[ENOTTY], 3-63, 7-69,

12-26

[ENXIO], 1-7, 1-13, 1-17,

1-20, 1-24, 1-36,

3-21, 3-32, 3-63, 4-7,

4-21, 4-25, 4-31,

5-12, 6-7, 6-30, 6-34,

7-168, 7-181, 9-9,

9-13, 10-16, 10-21,

12-26

[EOPNOTSUPP], 1-3, 1-10,

1-36, 3-42, 3-50,

3-55, 3-63, 4-10,

5-12, 6-14, 6-18,

6-21, 7-23, 7-28,

7-31, 7-77, 12-26

[EOSSNOTRUNNING], 1-7,

1-13, 1-17, 1-20,

1-24, 1-36, 4-7, 4-21,

4-25, 4-31, 5-12,

5-15, 6-8, 6-30, 6-34,

7-168, 7-181, 9-9,

9-13, 12-26

[EPARTIAL], 12-26

[EPERM], 1-13, 1-17, 1-20,

1-24, 1-36, 3-43, 4-4,

4-7, 4-25, 4-31, 4-35,

5-3, 5-12, 6-30, 7-13,

7-33, 7-35, 7-36,

7-44, 7-50, 8-54,

8-71, 9-9, 9-13,

12-26

[EPFNOSUPPORT], 12-26

[EPIPE], 7-23, 7-28, 7-32,

10-16, 10-21, 12-27

[EPROTONOSUPPORT],

7-74, 7-77, 12-27

[EPROTOTYPE], 1-30, 7-74,

7-77, 12-27

[ERANGE], 7-13, 7-21,

12-27

[EROFS], 1-7, 1-10, 1-17,

1-20, 1-36, 3-34, 4-7,

4-25, 4-31, 5-12,

6-30, 6-34, 7-181,

9-9, 9-13, 12-27

Hewlett-Packard Company

Index

[ESHUTDOWN], 12-27

[ESOCKTNOSUPPORT],

12-27

[ESPIERR], 12-27

[ESPIPE], 4-12, 12-27

[ESRCH], 3-43, 3-48, 4-4,

7-35, 12-27

[ETANOTRUNNING], 7-74,

7-77, 12-27

[ETIMEDOUT], 1-30, 6-4,

6-12, 6-14, 6-18,

6-21, 10-16, 10-21,

12-27

[ETXTBSY], 1-7, 1-36, 2-9,

2-17, 2-25, 2-33,

2-41, 2-49, 5-12,

6-30, 8-15, 8-29,

8-54, 8-71, 9-9, 9-13,

12-27

[EUNKNOWN], 2-9, 2-17,

2-25, 2-33, 2-41,

2-49, 3-12, 8-15,

8-29, 8-39, 8-55,

8-71, 12-27

[EVERSION], 12-27

[EWOULDBLOCK], 1-3,

6-14, 6-18, 6-21,

7-24, 7-28, 7-32,

12-27

[EWRONGID], 1-39, 1-41,

3-7, 3-21, 3-30, 3-32,

3-63, 4-12, 6-4, 6-12,

10-16, 10-21, 12-27

[EXDEV], 4-7, 6-30, 12-28

[EXDRDECODE], 12-28

[EXDRENCODE], 12-28 error condition values, 12-21 to

12-28 exec set of functions, 2-2, 2-3 to

2-10, 2-11 to 2-18, 2-19 to

2-26, 2-27 to 2-34, 2-35 to

2-42, 2-43 to 2-50 execl function, 2-3 to 2-10 execle function, 2-11 to 2-18 execlp function, 2-19 to 2-26 execv function, 2-27 to 2-34 execve function, 2-35 to 2-42

Index

7

execvp function, 2-43 to 2-50

_exit function, 2-51 to 2-52

Index

8

F fast mutex, 5-86 fcntl function, 3-2 to 3-8

FIFOs creating, 4-27 propagating open, 8-4, 8-19,

8-38, 8-43, 8-59 file access flags

O_RDONLY, 5-5

O_RDWR, 5-5

O_WRONLY, 5-5 file access modes, 1-38, 1-40 file descriptors checking I/O status of, 7-5 closing, 1-25 controlling, 1-40, 3-2 duplicating, 1-38, 1-40 sets for checking I/O status,

7-5 file format archive library, 11-2 cpio, 11-4 tar, 11-35 file mode creation mask, setting and getting, 9-4 file status flags, 1-38, 1-40

O_APPEND, 5-6

O_CREAT, 5-5

O_EXCL, 5-6

O_NOCTTY, 5-6

O_NONBLOCK, 5-6, 5-14

O_SYNC, 5-7

O_TRUNC, 5-6 file system hierarchy, 12-36 renaming files and directories, 6-24,

6-26 file type flags

S_IFCHR, 3-15, 4-15, 7-160

S_IFDIR, 3-15, 4-15, 4-23,

7-161

Hewlett-Packard Company

OSS System Calls Reference Manual

S_IFIFO, 3-15, 4-15, 7-161

S_IFREG, 1-32, 3-15, 4-15,

5-8, 7-161

S_IFSOCK, 3-15, 4-15,

7-161

S_ISVTX, 1-14, 1-32, 3-16,

4-15, 4-23, 5-8,

7-161

S_NONSTOP, 1-15, 1-32,

3-16, 4-15, 4-23, 5-8,

7-161 filename, 12-29 to 12-35 files

/dev/null, 11-18

/dev/tty, 11-57

/etc/termcap, 11-38 access, 1-5, 1-14, 9-11 access flags. See file access flags access modes, 1-38, 1-40, 3-2 access time, 9-11 ar, 11-2 archive library, 11-2 changing access, 1-14 changing length of, 3-33 changing owner and group

IDs, 1-18 checking I/O status of file objects, 7-5 closing, 1-25 control operations, 1-38,

1-40, 3-2 controlling a device file, 3-60 core memory image, 11-3 cpio, 11-4 creating, 1-31, 5-4 creating a directory, 4-27 creating a FIFO, 4-27 creating a link for, 4-5 creating a pipe, 5-14 creating a regular file, 4-27 creating a special file, 4-27 creation mask, 9-4 descriptors. See file descriptors determining accessibility,

1-5

527186-003

527186-003 device file control, 3-60 dir, 11-7 directory. See directory directory format, 11-7 executable, 2-2, 2-3, 2-11,

2-19, 2-27, 2-35,

2-43, 8-2, 8-16, 8-40,

8-56, 12-39 executing, 2-2, 2-3, 2-11,

2-19, 2-27, 2-35,

2-43, 8-2, 8-16, 8-40,

8-56, 12-39 floating-point specifications,

11-8 group ID, 1-18 limits specifications, 11-10 locks, 3-2 modification time, 9-11 modifications, saving, 3-31 names for, 12-29 null, 11-18 open, 8-38 opening for reading or writing, 1-31, 5-4 owner ID, 1-18 pathnames for, 12-29 permission, changing, 1-14 process snapshot, 11-3 propagating open, 8-4, 8-19,

8-43, 8-59 providing information about,

3-14, 4-13, 7-159 read-write offset setting, 4-11 reading from, 6-2, 6-9 removing a link from, 9-7 renaming, 6-23, 6-24, 6-26 saveabend, 10-3, 10-9, 11-3 setting access and modification times,

9-11 setting and getting creation mask value, 9-4 sharing Guardian, 3-11, 8-38,

8-43, 8-60 signal, 11-20 size, 9-2 status flags. See file status flags

Index symbolic link. See symbolic link tar, 11-35 termcap, 11-38 termios, 11-51 tty, 11-57 types. See file type flags writing changes to disk, 3-31 writing to, 10-13, 10-18 fileset information, 3-23, 7-169 flat segments, 7-45 float header file, 11-8 to 11-9 fork function, 3-9 to 3-13 format of directories, 11-7 fstat function, 3-14 to 3-22 fstatvfs function, 3-23 to 3-30 fsync function, 3-31 to 3-32 ftruncate function, 3-33 to 3-34

Hewlett-Packard Company

G get fileset information, 3-23, 7-169 getegid function, 3-35 geteuid function, 3-36 getgid function, 3-37 getgroups function, 3-38 gethostname function, 3-39 getlogin function, 3-40 getpeername function, 3-41 to 3-42 getpgid function, 3-43 getpgrp function, 3-44 getpid function, 3-45 getppid function, 3-46 getpriority function, 3-47 to 3-48 getsockname function, 3-49 to 3-50 getsockopt function, 3-51 to 3-56 gettimeofday function, 3-57 to 3-58 getuid function, 3-59 group ID changing for a file, 1-18 returning effective, 3-35 returning for a process, 3-43,

3-44 returning real, 3-37

Index

9

setting for a process, 7-34,

7-36 setting real and effective,

7-33 group list, returning for current process, 3-38 gtacl variables, PMSEARCHLIST,

12-12

Guardian environment, using from

_exit function, 2-52 access function, 1-6 chdir function, 1-11 chmod function, 1-16 chown function, 1-19 chroot function, 1-23 creat function, 1-34 execl function, 2-8 execle function, 2-16 execlp function, 2-24 execv function, 2-32 execve function, 2-40 execvp function, 2-48 fork function, 3-9 getpgid function, 3-43 getpgrp function, 3-44 getpid function, 3-45 getppid function, 3-46 getpriority function, 3-47 gettimeofday function, 3-57 ioctl function, 3-62 kill function, 4-2 link function, 4-6 lstat function, 4-20 message queue, 4-34, 4-37,

4-40, 4-43 mkdir function, 4-23 mknod function, 4-29 msgget function, 4-34, 4-37 msgrcv function, 4-40 msgsnd function, 4-43 nice function, 5-3 open function, 5-9 pipe function, 5-14 readlink function, 6-6 rename function, 6-27 rename_oss function, 6-24,

6-27 rmdir function, 6-33 select function, 7-7

Index

10 Hewlett-Packard Company

OSS System Calls Reference Manual semaphores, 7-16 semctl function, 7-12 semget function, 7-16 semop function, 7-20 setpgid function, 7-34 setsid function, 7-36 shared memory, 7-55 shmat function, 7-46 shmctl function, 7-49 shmdt function, 7-51 shmget function, 7-56 sigaction function, 7-60 sigpending function, 7-64 sigprocmask function, 7-66 sigsuspend function, 7-67 socket function, 7-72 socketpair function, 7-76 stat function, 7-166 statvfs function, 7-176 symlink function, 7-179 tdm_execve function, 8-3 tdm_execvep function, 8-17 tdm_fork function, 8-31 tdm_spawn function, 8-42 tdm_spawnp function, 8-58 unlink function, 9-7 utime function, 9-12 wait function, 10-2 waitpid function, 10-8

Guardian environment, using in rename function, 6-24, 6-27 rename_oss function, 6-27

Guardian objects, using on access function, 1-5 chdir function, 1-11 chmod function, 1-16 chown function, 1-18 chroot function, 1-22 creat function, 1-33 fstat function, 3-19 fsync function, 3-31 ioctl function, 3-62 kill function, 4-2 link function, 4-6 lstat function, 4-18 mknod function, 4-29 nice function, 5-2 open function, 5-8 read function, 6-3

527186-003

readlink function, 6-6 readv function, 6-10 rename function, 6-27 rename_oss function, 6-27 select function, 7-7 stat function, 7-165 symlink function, 7-179 umask function, 9-4 utime function, 9-11 write function, 10-15 writev function, 10-20

H hexadecimal ASCII character set,

12-2 hierarchy, file system, 12-36 to 12-37 host, returning name of current, 3-39 hostname, returning for current host,

3-39

I

I/O status, checking file descriptor sets for, 7-5 implementation-dependent constants,

11-10 interface for terminals, 11-51, 11-57 ioctl function, 3-60 to 3-63

K kill function, 4-2 to 4-4

Index

L limits header file, 11-10 to 11-16 link creating, 4-5 removing, 9-7 symbolic. See symbolic link link function, 4-5 to 4-8 listen function, 4-9 to 4-10 locales, 12-9 locks, file, 3-2 login name, returning and setting,

3-40 lseek function, 4-11 to 4-12 lstat function, 4-13 to 4-21

M macros

FD_CLR, 7-5 to 7-9

FD_ISSET, 7-5 to 7-9

FD_SET, 7-5 to 7-9

FD_ZERO, 7-5 to 7-9 for cpio, 11-6

S_ISEXPANDOBJECT,

3-20, 4-20, 7-166

S_ISGUARDIANOBJECT,

3-19, 4-18, 7-165

WCOMPLETION, 10-3,

10-8

WEXITSTATUS, 10-8

WIFABENDED, 10-3, 10-9

WIFEXITED, 10-3, 10-9

WIFSAVEABEND, 10-3,

10-9

WIFSIGNALED, 10-3, 10-9

WIFSTOPPED, 10-3, 10-9

WSTOPSIG, 10-4, 10-9

WTERMSIG, 10-4, 10-9 mask, file mode creation, 9-4 mask, signal changing, 7-65, 7-67 examining, 7-65 math header file, 11-17

Index

11 527186-003 Hewlett-Packard Company

Index

12 memory image file, 11-3 message queue after disk process failures,

4-37 after processor failures, 4-37 cleaning up identifiers, 4-37 creating, 4-36 obtaining key for, 4-37 performing control operations on, 4-33 receiving a message from,

4-39 removing, 4-33 returning the identifier for,

4-36 sending a message to, 4-42 uniqueness of identifiers,

4-37 use between environments,

4-34, 4-37, 4-40,

4-43 messages receiving from a message queue, 4-39 receiving from connected sockets, 6-13 receiving from unconnected sockets, 6-16 receiving using a message structure, 6-19 sending to a message queue,

4-42 sending to connected sockets, 7-22 sending to unconnected sockets, 7-29 sending using a message structure, 7-25 mkdir function, 4-22 to 4-26 mknod function, 4-27 to 4-32 mode values creat function, 1-32 mkdir function, 4-23 open function, 5-8 msgctl function, 4-33 to 4-35 msgget function, 4-36 to 4-38 msgrcv function, 4-39 to 4-41

Hewlett-Packard Company

OSS System Calls Reference Manual msgsnd function, 4-42 to 4-44 mutex fast, 5-86 nonrecursive, 5-86 recursive, 5-86

N nice function, 5-2 to 5-3 nonrecursive mutex, 5-86 null file, 11-18

O obase values, bc utility, 11-14 octal ASCII character set, 12-2 oflag values, open function, 5-7 open function, 5-4 to 5-13 osh variables

Guardian PARAMs, 12-9

LOGNAME, 12-11

PATH, 12-12

PWD, 12-13

OSS process ID (PID), 3-45, 3-46 owner ID, changing for a file, 1-18

P parent OSS process ID, returning,

3-46 pathname, 12-29 to 12-35 peer address, returning for a socket,

3-41 peer name, returning for a socket,

3-41 permission, changing for a file, 1-14 pipe function, 5-14 to 5-15 pipes creating, 5-14 propagating open, 8-4, 8-19,

527186-003

8-38, 8-43, 8-59

POSIX-defined minimum values,

11-13 process attaching shared memory segment, 7-45 changing scheduling priority,

5-2 changing signal mask, 7-65,

7-67 cleanup on exit, 2-51 creating a session, 7-36 creating via fork, 3-9 creating via tdm_fork, 8-30 effective group ID, 3-35,

7-33 effective user ID, 3-36, 7-44 examining signal mask, 7-65 executing new, 8-30, 8-40,

8-56, 12-39 exiting, 2-51 forking, 3-9, 8-30 group ID, 3-43, 3-44, 7-33,

7-36 performing shared memory control operations,

7-48 real group ID, 3-37, 7-33 real user ID, 3-59, 7-44 receiving signals, 7-60 returning effective group ID,

3-35 returning effective user ID,

3-36 returning group ID, 3-43,

3-44 returning group list, 3-38 returning OSS process ID,

3-45 returning parent OSS process

ID, 3-46 returning real group ID, 3-37 returning scheduling priority,

3-47 returning user ID, 3-36, 3-59 saved-set group ID, 7-33 saved-set user ID, 7-44 sending a signal to, 4-2 setting effective user ID,

7-44

527186-003 Hewlett-Packard Company

Index setting group ID, 7-34, 7-36 setting real user ID, 7-44 specifying signal actions,

7-60 suspending, 7-67, 10-2, 10-7,

10-13, 10-18 terminating, 2-51 transport-provider, 7-79, 7-81 user ID, 3-36, 3-59, 7-44 waiting for caught signals,

10-2 waiting for child process to stop, 10-7 process attributes default Guardian, 8-6, 8-21,

8-32, 8-46, 8-62

Guardian, 2-6, 2-14, 2-22,

2-30, 2-38, 2-46,

3-10

OSS, 2-5, 2-14, 2-22, 2-29,

2-38, 2-46, 3-9, 8-6,

8-20, 8-31, 8-45,

8-61 setting Guardian, 8-8, 8-22,

8-33, 8-47, 8-64 process deletion message, Guardian,

4-3 process group getting scheduling priority,

3-47 specifying, 8-44, 8-61 process ID, OSS, returning, 3-45,

3-46 process image identifying file, 2-3, 2-11,

2-19, 2-27, 2-35,

2-43, 8-3, 8-17, 8-42,

8-58 replacing current, 2-2, 2-3,

2-11, 2-19, 2-27,

2-35, 2-43, 8-2, 8-16,

8-40, 8-56, 12-39 using new, 2-2, 2-3, 2-11,

2-19, 2-27, 2-35,

2-43, 8-2, 8-16, 8-40,

8-56, 12-39 process snapshot file, 11-3 process_extension_results structure,

Index

13

12-39 to 12-47 protocol, supporting sockets, 7-71 pthread_atfork function, 5-16 pthread_attr_destroy function, 5-18 pthread_attr_getdetachstate function,

5-19 pthread_attr_getguardsize_np function, 5-20 pthread_attr_getinheritsched function, 5-21 pthread_attr_getschedparam function, 5-22 pthread_attr_getschedpolicy function, 5-23 pthread_attr_getstackaddr function,

5-24 pthread_attr_getstacksize function,

5-25 pthread_attr_init function, 5-26 pthread_attr_setdetachstate function,

5-28 pthread_attr_setguardsize_np function, 5-30 pthread_attr_setinheritsched function, 5-32 pthread_attr_setschedparam function,

5-34 pthread_attr_setschedpolicy function,

5-36 pthread_attr_setstacksize function,

5-37 pthread_cancel function, 5-38 pthread_cleanup_pop function, 5-40 pthread_cleanup_push function, 5-41 pthread_cond_broadcast function,

5-42 pthread_cond_destroy function, 5-43 pthread_cond_init function, 5-44 pthread_cond_signal function, 5-46 pthread_cond_signal_int_np function, 5-47 pthread_cond_timedwait function,

5-48 pthread_cond_wait function, 5-50 pthread_condattr_destroy function,

5-52 pthread_condattr_init function, 5-53

OSS System Calls Reference Manual pthread_create function, 5-55 pthread_delay_np function, 5-58 pthread_detach function, 5-59 pthread_equal function, 5-60 pthread_exit function, 5-61 pthread_get_expiration_np function,

5-62 pthread_getattr_np function, 5-63 pthread_getconcurrency function,

5-64 pthread_getschedparam function,

5-65 pthread_getspecific function, 5-67 pthread_join function, 5-68 pthread_key_create function, 5-70 pthread_key_delete function, 5-72 pthread_kill function, 5-73 pthread_lock_global_np function,

5-75 pthread_mutex_destroy function,

5-76 pthread_mutex_init function, 5-77 pthread_mutex_lock function, 5-79 pthread_mutex_trylock function,

5-80 pthread_mutex_unlock function, 5-81 pthread_mutexattr_destroy function,

5-82 pthread_mutexattr_getkind_np function, 5-83 pthread_mutexattr_init function, 5-84 pthread_mutexattr_setkind_np function, 5-86 pthread_once function, 5-88 pthread_self function, 5-89 pthread_setcancelstate function, 5-90 pthread_setcanceltype function, 5-92 pthread_setconcurrency function,

5-94 pthread_setschedparam function,

5-95 pthread_setspecific function, 5-97 pthread_sigmask function, 5-98 pthread_testcancel function, 5-100 pthread_unlock_global_np function,

5-101

Index

14 Hewlett-Packard Company 527186-003

Index

R read function, 6-2 to 6-5 read-write offset, setting for a file,

4-11 readlink function, 6-6 to 6-8 readv function, 6-9 to 6-12 recursive mutex, 5-86 recv function, 6-13 to 6-15 recvfrom function, 6-16 to 6-18 recvmsg function, 6-19 to 6-22 remote objects, using on fstat function, 3-20 lstat function, 4-20 stat function, 7-166 rename function, 6-23, 6-24 to 6-25,

6-26 to 6-31 rename_guardian function, 6-24 to

6-25, 6-27 rename_oss function, 6-24, 6-26 to

6-31 rmdir function, 6-32 to 6-35 root directory, changing effective,

1-22

S

Safeguard, protecting processes, 4-3 save file, 11-3 saveabend file, 11-3 scale value, bc utility, 11-14 sched_get_priority_max function, 7-2 sched_get_priority_min function, 7-3 sched_yield function, 7-4 scheduling priority getting, 3-47 setting, 5-2 select function, 7-5 to 7-9 semaphore sets creating new ID, 7-15 obtaining key for, 7-16 performing control operations on, 7-10 performing operations on,

7-18 propagating to child process,

7-16, 8-38, 8-44,

8-60

527186-003 Hewlett-Packard Company propagating to new process,

2-5, 2-13, 2-21, 2-29,

2-37, 2-45, 8-5, 8-19 returning ID, 7-15 semaphores performing control operations on, 7-10 performing operations on,

7-18 semctl function, 7-10 to 7-14 semget function, 7-15 to 7-17 semop function, 7-18 to 7-21 send function, 7-22 to 7-24 sendmsg function, 7-25 to 7-28 sendto function, 7-29 to 7-32 session, creating, 7-36 setgid function, 7-33 setpgid function, 7-34 to 7-35 setsid function, 7-36 setsockopt function, 7-37 to 7-43 setuid function, 7-44 shared memory address range, 7-45, 7-51 after disk process failures,

7-55 after processor failures, 7-55 attaching segment, 7-45 cleaning up identifiers, 7-51,

7-55 control operations, 7-48 creating segment, 7-53 detaching segment, 2-5, 2-13,

2-21, 2-29, 2-37,

2-45, 7-51, 8-5, 8-19,

8-38, 8-44, 8-60 memory alignment of segments, 7-46 number of segments, 7-46,

7-55 obtaining key for, 7-55 performing control operations on, 7-48 propagating, 7-46, 8-38 returning identifier of, 7-53 sizes of segments, 7-55 swap file for, 7-55 uniqueness of identifiers,

7-55

Index

15

Index

− use between environments,

7-55 shell variables

CDPATH, 12-4

COMP_ROOT, 12-5

EDITOR, 12-8

EMS_COLLECTOR, 12-8

ENV, 12-9

EXINIT, 12-9

FCEDIT, 12-9

FPATH, 12-9

HISTFILE, 12-9

HISTSIZE, 12-9

HOME, 12-9

IFS, 12-9, 12-20

JAVA_HOME, 12-9

LANG, 12-9

LC_ALL, 12-10

LC_COLLATE, 12-10

LC_CTYPE, 12-10

LC_MESSAGES, 12-10

LC_MONETARY, 12-11

LC_NUMERIC, 12-11

LC_TIME, 12-11

LOCPATH, 12-11

MANPATH, 12-11

NLSPATH, 12-12

PATH, 12-12

PRINTER, 12-12

PS1, 12-13, 12-20

PS2, 12-13, 12-20

PS3, 12-13

PS4, 12-13

SHELL, 12-14

SWAPVOL, 12-15

TERM, 12-16

TERMCAP, 12-16

TERMINFO, 12-16

TERMPATH, 12-16

TMOUT, 12-17

TMPDIR, 12-17

TZ, 12-17

USER, 12-19

UTILSGE, 12-19

VISUAL, 12-19

ZCPU, 12-19 shmat function, 7-45 to 7-47

16

OSS System Calls Reference Manual shmctl function, 7-48 to 7-50 shmdt function, 7-51 to 7-52 shmget function, 7-53 to 7-57 shutdown function, 7-58 to 7-59 sigaction function, 7-60 to 7-63 signal action, 7-60 to 7-63 signal file, 11-20 to 11-26 signal mask changing, 7-65, 7-67 examining, 7-65 signals blocked, 7-64, 7-65 blocking, 7-61, 7-65, 7-67 catching, 2-5, 2-13, 2-21,

2-29, 2-37, 2-45 declarations used for, 11-20 definitions used for, 11-22 examining pending, 7-64 propagating actions, 8-5,

8-19, 8-44, 8-60 sending to a process or process group, 4-2 specifying, 7-60 specifying actions for, 7-61 specifying handlers for, 7-61 specifying options for, 7-62 suspending process execution, 7-67 table of, 11-22 variables used for, 11-22 waiting for, 7-67 sigpending function, 7-64 sigprocmask function, 7-65 to 7-66 sigsuspend function, 7-67 to 7-68 sockatmark function, 7-69 to 7-70 socket accepting a connection, 1-2 binding a name, 1-8 connecting, 1-27 controlling socket communication, 7-37 creating, 7-71 creating a connected pair,

7-75 creating by accepting a connection, 1-2 creating endpoints, 7-71 destroying, 1-25 disabling send and receive operations, 7-58

Hewlett-Packard Company 527186-003

inherited by a process, 3-41,

3-49 listening for connections, 4-9 locally bound address, 3-49 name, 1-8 options for, 3-51 out-of-band data, 7-40 out-of-band mark, 7-69 propagating existing, 8-5,

8-19, 8-38, 8-43,

8-60 receiving messages from connected, 6-13 receiving messages from unconnected, 6-16 receiving messages using a message structure,

6-19 returning locally bound name, 3-49 returning options for, 3-51 returning peer address, 3-41 returning peer name, 3-41 returning transport-provider process name, 7-79 send and receive operations,

7-58 sending messages to connected, 7-22 sending messages to unconnected, 7-29 sending messages using a message structure,

7-25 setting options, 7-37 setting transport-provider process name, 7-81 socket function, 7-71 to 7-74 socket pair, creating, 7-75 socket_transport_name_get function,

7-79 to 7-80 socket_transport_name_set function,

7-81 to 7-82 socketpair function, 7-75 to 7-78 special file, creating, 4-27

SPT_ABORTTRANSACTION,

7-182

Index spt_accept function, 7-83 spt_awaitio function, 7-84

SPT_BEGINTRANSACTION,

7-183 spt_close function, 7-86 spt_connect function, 7-87

SPT_ENDTRANSACTION, 7-184 spt_fclose function, 7-88 spt_fd_read_ready function, 7-89 spt_fd_write_ready function, 7-90 spt_fflush function, 7-91 spt_fgetc function, 7-92 spt_fgets function, 7-93 spt_fgetwc function, 7-94 spt_FileIOHandler_p function, 7-95 spt_fork function, 7-96 spt_fprintf function, 7-97 spt_fputc function, 7-98 spt_fputs function, 7-99 spt_fputwc function, 7-100 spt_fread function, 7-101 spt_fwrite function, 7-102 spt_generateTag function, 7-103 spt_getc function, 7-104 spt_getchar function, 7-105 spt_gets function, 7-106 spt_getTMFConcurrentTransactions function, 7-107 spt_getw function, 7-108 spt_getwc function, 7-109 spt_getwchar function, 7-110 spt_INITRECEIVE function, 7-111 spt_interrupt function, 7-112 spt_interruptTag function, 7-113 spt_OSSFileIOHandler_p function,

7-114 spt_printf function, 7-115 spt_putc function, 7-116 spt_putchar function, 7-117 spt_puts function, 7-118 spt_putw function, 7-119 spt_putwc function, 7-120 spt_putwchar function, 7-121 spt_read function, 7-122 spt_readv function, 7-123 spt_RECEIVEREAD function, 7-124 spt_recv function, 7-126

527186-003 Hewlett-Packard Company Index

17

Index

− spt_recvfrom function, 7-127 spt_recvmsg function, 7-128 spt_regFile function, 7-129 spt_regFileIOHandler function,

7-130 spt_regOSSFileIOHandler function,

7-131 spt_regPathsendFile function, 7-132 spt_regPathsendTagHandler function,

7-133 spt_regTimerHandler function, 7-135 spt_REPLYX function, 7-136

SPT_RESUMETRANSACTION,

7-185 spt_select function, 7-137 spt_send function, 7-138 spt_sendmsg function, 7-139 spt_sendto function, 7-140

SPT_SERVERCLASS_DIALOG_ABORT_ function, 7-186

SPT_SERVERCLASS_DIALOG_BEGIN_ function, 7-187

SPT_SERVERCLASS_DIALOG_END_ function, 7-190

SPT_SERVERCLASS_DIALOG_SEND_ function, 7-191

SPT_SERVERCLASS_SEND_,

7-194

SPT_SERVERCLASS_SEND_INFO_

function, 7-197 spt_setOSSFileIOHandler function,

7-141 spt_setTMFConcurrentTransactions function, 7-142 spt_sleep function, 7-143 spt_system function, 7-144 spt_TimerHandler_p function, 7-145

SPT_TMF_GetTxHandle function,

7-146

SPT_TMF_Init function, 7-147

SPT_TMF_SetTxHandle function,

7-148 spt_unregFile function, 7-149 spt_unregOSSFileIOHandler function, 7-150 spt_unregPathsendTagHandler function, 7-151

18

OSS System Calls Reference Manual spt_usleep function, 7-152 spt_vfprintf function, 7-153 spt_vprintf function, 7-154 spt_waitpid function, 7-155 spt_wakeup function, 7-156 spt_write function, 7-157 spt_writev function, 7-158 spthread.h header, 11-27 st_atime, 3-18, 4-17, 7-163, 12-35

Standard POSIX threads, 5-16, 5-19,

5-21, 5-22, 5-23, 5-25, 5-28,

5-30, 5-32, 5-34, 5-37, 5-38,

5-40, 5-41, 5-43, 5-58, 5-59,

5-60, 5-61, 5-62, 5-64, 5-65,

5-67, 5-68, 5-75, 5-76, 5-77,

5-81, 5-82, 5-84, 5-88, 5-90,

5-92, 5-94, 5-95, 5-97, 5-98,

5-100, 5-101, 7-2, 7-3 standard POSIX threads, 7-62

Standard POSIX threads, 7-83, 7-84,

7-86, 7-87, 7-88, 7-89, 7-90,

7-91, 7-92, 7-93, 7-94, 7-95,

7-97, 7-98, 7-99, 7-100,

7-101, 7-102, 7-103, 7-104,

7-105, 7-106, 7-108, 7-109,

7-110, 7-111, 7-112, 7-113,

7-114, 7-115, 7-116, 7-117,

7-118, 7-119, 7-120, 7-121,

7-122, 7-123, 7-124, 7-126,

7-127, 7-128, 7-129, 7-130,

7-131, 7-135, 7-136, 7-137,

7-138, 7-139, 7-140, 7-141,

7-144, 7-145, 7-149, 7-150,

7-153, 7-154, 7-155, 7-156,

7-157, 7-158, 7-186, 7-187,

7-190, 7-191, 11-27 attribute object, 5-63 causing a wait, 5-48 creating, 5-55 creating a data key, 5-70 deleting a data key, 5-72 destroying a condition variable attributes object, 5-52 destroying a thread attributes object, 5-18 initializing a condition variable, 5-44, 5-53 initializing a thread attributes object, 5-26

Hewlett-Packard Company 527186-003

locking a mutex, 5-79 locking a mutex without waiting, 5-80 obtaining the guardsize attribute, 5-20 obtaining the mutex attribute type, 5-83 obtaining the thread identifier, 5-89

Pathsend file use, 7-132

Pathsend tags, 7-133, 7-151 setting the mutex type attribute, 5-86 setting the scheduling policy,

5-36 signaling, 5-73 suspension, 7-143, 7-152 thread attributes object, 5-24 thread-aware fork, 7-96

TMF use, 7-107, 7-142,

7-146, 7-147, 7-148 unblocking all threads on a condition variable,

5-42 unblocking on a condition variable, 5-46 unblocking on a condition variable from an interrupt handler,

5-47 waiting for a condition variable, 5-50 yielding the processor, 7-4 stat function, 7-159 to 7-168 status flags. See file status flags statvfs function, 7-169 to 7-177 structures inherit, 8-40, 8-57 iovec, 6-9 linger, 7-40 msgbuf, 4-40, 4-43 msghdr, 6-19, 7-25 msqid_ds, 4-43 process_extension, 8-2, 8-8,

8-16, 8-22, 8-30,

8-41, 8-57 process_extension_results,

8-2, 8-13, 8-16, 8-27,

8-30, 8-37, 8-41,

8-52, 8-57, 12-39

527186-003 Hewlett-Packard Company

Index sembuf, 7-18 shmid_ds, 7-48 sigaction, 7-60 sockaddr, 1-27, 6-16, 7-29 stat, 3-14, 4-13, 7-159, 12-35 statvfs, 3-23, 7-169 termios, 11-51 timeval, 3-57 timezone, 3-57 utimebuf, 9-11 utsname, 9-5 winsize, 3-62 swap file, shared segment, 7-55 symbolic link making, 7-178 names, 12-29 providing information about,

4-13 reading from, 6-6 symbolic value

_POSIX2_BC_BASE_MAX,

11-14

_POSIX2_BC_DIM_MAX,

11-14

_POSIX2_BC_SCALE_MAX,

11-14

_POSIX2_BC_STRING_MAX,

11-14

_POSIX2_COLL_WEIGHTS_MAX,

11-14

_POSIX2_EXPR_NEST_MAX,

11-14

_POSIX2_LINE_MAX,

11-14

_POSIX2_RE_DUP_MAX,

11-14

_POSIX_ARG_MAX, 11-13

_POSIX_CHILD_MAX,

11-13

_POSIX_FD_SETSIZE,

11-13

_POSIX_HIWAT, 11-13

_POSIX_LINK_MAX, 11-13

_POSIX_MAX_CANON,

11-13

_POSIX_MAX_INPUT,

11-13

_POSIX_NAME_MAX,

11-13

Index

19

Index

20

_POSIX_NGROUPS_MAX,

11-13

_POSIX_OPEN_MAX,

11-13

_POSIX_PATH_MAX,

11-13

_POSIX_PIPE_BUF, 11-13

_POSIX_QLIMIT, 11-13

_POSIX_SSIZE_MAX,

11-13

_POSIX_STREAM_MAX,

11-14

_POSIX_TZNAME_MAX,

11-14

_TPC_BAD_ARGV, 12-40

_TPC_BAD_CPU, 12-43

_TPC_BAD_CREATE_OPTIONS,

12-43

_TPC_BAD_DEBUG_OPTIONS,

12-43

_TPC_BAD_DEFINES,

12-40, 12-44

_TPC_BAD_ENVIRON,

12-41

_TPC_BAD_ENVP, 12-41

_TPC_BAD_ERROR_DETAIL,

12-41

_TPC_BAD_EXTENSION,

12-41, 12-44

_TPC_BAD_EXTSWAP,

12-41, 12-44

_TPC_BAD_FDMAP, 12-41

_TPC_BAD_HOMETERM,

12-41, 12-44

_TPC_BAD_INHERIT,

12-41, 12-44

_TPC_BAD_INTERNAL,

12-41, 12-44

_TPC_BAD_INTERPRETER,

12-44

_TPC_BAD_JOB, 12-45

_TPC_BAD_MEM, 12-45

_TPC_BAD_NAME_OPTIONS,

12-45

_TPC_BAD_OSS_OPTIONS,

12-45

_TPC_BAD_OUTPUT,

12-42, 12-45

_TPC_BAD_OUTPUT_LEN,

12-42, 12-45

Hewlett-Packard Company

OSS System Calls Reference Manual

_TPC_BAD_PARAM_REFERENCE,

12-40

_TPC_BAD_PARAM_VALUE,

12-43

_TPC_BAD_PARMLIST,

12-42, 12-45

_TPC_BAD_PFS_SIZE,

12-45

_TPC_BAD_PIMFILE,

12-42, 12-46

_TPC_BAD_PRIO, 12-46

_TPC_BAD_PRIVATE_LIST,

12-42, 12-46

_TPC_BAD_PRIVLIST,

12-42, 12-46

_TPC_BAD_PROCESS_NAME,

12-42, 12-46

_TPC_BAD_SWAP, 12-43,

12-46

_TPC_BAD_UC, 12-43,

12-46

_TPC_BAD_UL, 12-43,

12-46

_TPC_BOTH_DEFINES,

8-10, 8-24, 8-35,

8-49, 8-66

_TPC_CODEFILE_INSPECT_SAVEABEND,

8-11, 8-25, 8-36,

8-50, 8-67

_TPC_DEBUG_NOSAVE,

8-11, 8-25, 8-36,

8-50, 8-67

_TPC_DEBUG_SAVEABEND,

8-12, 8-26, 8-36,

8-51, 8-67

_TPC_ENABLE_DEFINES,

8-11, 8-24, 8-35,

8-49, 8-66

_TPC_ENTER_DEBUG,

8-12, 8-26, 8-36,

8-51, 8-67

_TPC_GENERATE_NAME,

8-10, 8-24, 8-35,

8-49, 8-65

_TPC_HIGHPIN_OFF, 8-11,

8-25, 8-35, 8-50,

8-66

_TPC_IGNORE_FORCEPIN_ATTR,

8-11, 8-25, 8-36,

8-50, 8-66

527186-003

527186-003

_TPC_INSPECT_NOSAVE,

8-12, 8-26, 8-36,

8-51, 8-67

_TPC_INSPECT_SAVEABEND,

8-12, 8-26, 8-37,

8-51, 8-67

_TPC_NAME_SUPPLIED,

8-10, 8-24, 8-35,

8-49, 8-65

_TPC_NO_NAME, 8-10,

8-24, 8-35, 8-49,

8-65

_TPC_OVERRIDE_DEFMODE,

8-11, 8-25, 8-36,

8-50, 8-66

_TPC_PROCESS_DEFINES_ONLY,

8-11, 8-25, 8-36,

8-50, 8-66

_TPC_SUPPLIED_DEFINES_ONLY,

8-11, 8-25, 8-36,

8-50, 8-67

AF_INET, 7-71, 7-79, 7-81

AF_INET6, 7-71, 7-79, 7-81

AF_UNIX, 7-71, 7-75, 7-79,

7-81

ARG_MAX, 11-14

BC_BASE_MAX, 11-10

BC_DIM_MAX, 11-10

BC_SCALE_MAX, 11-10

BC_STRING_MAX, 11-10

BRKINT, 11-51

CHAR_BIT, 11-11

CHAR_MAX, 11-11

CHAR_MIN, 11-11

CHARCLASS_NAME_MAX,

11-11

CHILD_MAX, 11-14

CLOCAL, 11-52

COLL_WEIGHTS_MAX,

11-11

CREAD, 11-52

CS5, 11-53

CS6, 11-53

CS7, 11-53

CS8, 11-53

CSIZE, 11-52

CSTOPB, 11-53

DBL_EPSILON, 11-8

DBL_MANT_DIG, 11-8

Hewlett-Packard Company

Index

DBL_MAX, 11-8

DBL_MAX_10_EXP, 11-8

DBL_MAX_EXP, 11-8

DBL_MIN, 11-8

DBL_MIN_10_EXP, 11-8

DBL_MIN_EXP, 11-8

ECHO, 11-53

ECHOE, 11-53

ECHOK, 11-53

ECHONL, 11-53

EXPR_NEST_MAX, 11-11

F_DUPFD, 3-2, 3-5

F_GETFD, 3-3, 3-5

F_GETFL, 3-3, 3-5

F_GETLK, 3-4, 3-5

F_GETOWN, 3-4, 3-5

F_SETFD, 3-3, 3-5

F_SETFL, 3-3, 3-5

F_SETLK, 3-4, 3-5

F_SETLKW, 3-4, 3-5

F_SETOWN, 3-4, 3-5

F_UNLCK, 3-4

FD_CLOEXEC, 1-38, 1-40,

5-14

FD_SETSIZE, 7-7

FIONBIO, 3-60

FIONREAD, 3-60

FLT_EPSILON, 11-8

FLT_MANT_DIG, 11-8

FLT_MAX, 11-8

FLT_MAX_10_EXP, 11-8

FLT_MAX_EXP, 11-8

FLT_MIN, 11-8

FLT_MIN_10_EXP, 11-8

FLT_MIN_EXP, 11-8

GETALL, 7-11

GETNCNT, 7-11, 7-12

GETPID, 7-11, 7-13

GETVAL, 7-11, 7-13

GETZCNT, 7-11, 7-13

HUGE_VAL, 11-17

HUPCL, 11-53

ICANON, 11-53

ICRNL, 11-51

IEXTEN, 11-54

IGNBRK, 11-51

IGNCR, 11-51

IGNPAR, 11-51

INLCR, 11-51

Index

21

Index

22

INPCK, 11-51

INT_BIT, 11-11

INT_MAX, 11-11

INT_MIN, 11-11

IOV_MAX, 11-14

IP_ADD_MEMBERSHIP,

7-38

IP_DROP_MEMBERSHIP,

7-38

IP_MULTICAST_IF, 3-52,

7-38

IP_MULTICAST_LOOP,

3-52, 7-39

IP_MULTICAST_TTL, 3-52,

7-39

IP_OPTIONS, 3-52, 7-38

IPC_CREAT, 7-15, 7-53

IPC_EXCL, 7-15, 7-53

IPC_NOWAIT, 7-19

IPC_PRIVATE, 7-15, 7-54

IPC_RMID, 4-33, 7-12, 7-48

IPC_SET, 4-33, 7-10, 7-12,

7-48

IPC_SETNONFT, 4-33

IPC_STAT, 4-34, 7-10, 7-12,

7-48

IPPROTO_IP, 3-51, 7-37

IPPROTO_IPV6, 3-51, 7-37

IPPROTO_TCP, 3-51, 7-37

IPV6_JOIN_GROUP, 7-37

IPV6_LEAVE_GROUP,

7-38

IPV6_MULTICAST_HOPS,

3-51, 7-38

IPV6_MULTICAST_IF,

3-51, 7-38

IPV6_MULTICAST_LOOP,

3-52, 7-38

IPV6_UNICAST_HOPS,

3-52, 7-38

IPV6_V6ONLY, 3-52, 7-38

ISIG, 11-54

ISTRIP, 11-51

IXANY, 11-51

IXOFF, 11-51

IXON, 11-52

LDBL_EPSILON, 11-8

LDBL_MANT_DIG, 11-8

LDBL_MAX, 11-8

Hewlett-Packard Company

OSS System Calls Reference Manual

LDBL_MAX_10_EXP, 11-8

LDBL_MAX_EXP, 11-8

LDBL_MIN, 11-8

LDBL_MIN_10_EXP, 11-8

LDBL_MIN_EXP, 11-8

LINE_MAX, 11-11

LINK_MAX, 11-14

LLONG_BIT, 11-11

LLONG_MAX, 11-11

LLONG_MIN, 11-11

LONG_BIT, 11-11

LONG_MAX, 11-11

LONG_MIN, 11-11

M_1_PI, 11-17

M_2_PI, 11-17

M_2_SQRTPI, 11-17

M_E, 11-17

M_LN10, 11-17

M_LN2, 11-17

M_LOG10E, 11-17

M_LOG2E, 11-17

M_PI, 11-17

M_PI_2, 11-17

M_PI_4, 11-17

M_SQRT1_2, 11-17

M_SQRT2, 11-17

MAX_CANON, 11-15

MAX_INPUT, 11-15

MAXFLOAT, 11-17

MB_LEN_MAX, 11-11

MSG_CTRUNC, 6-20

MSG_DONTROUTE, 7-22,

7-25, 7-29

MSG_OOB, 6-13, 6-16,

6-19, 6-20, 7-22,

7-25, 7-29

MSG_PEEK, 6-13, 6-16,

6-19

MSG_TRUNC, 6-20

NAME_MAX, 11-15

NL_ARGMAX, 11-12

NL_LANGMAX, 11-15

NL_MSGMAX, 11-12

NL_NMAX, 11-12

NL_SETMAX, 11-12

NL_TEXTMAX, 11-12

NOFLSH, 11-54

O_NONBLOCK, 6-3, 6-10,

6-13, 10-14, 10-19

527186-003

527186-003

OCRNL, 11-52

ONLCR, 11-52

ONLRET, 11-52

ONOCR, 11-52

OPEN_MAX, 11-15

OPOST, 11-52

PARENB, 11-53

PARMRK, 11-52

PARODD, 11-53

PATH_MAX, 11-12

PIPE_BUF, 10-14, 10-19,

11-12

PRIO_PGRP, 3-47

PRIO_PROCESS, 3-47

PRIO_USER, 3-47

RE_DUP_MAX, 11-12

S_IFCHR, 3-15, 4-15, 4-27,

7-160

S_IFDIR, 3-15, 4-15, 4-23,

4-27, 7-161

S_IFIFO, 3-15, 4-15, 4-27,

7-161

S_IFMT, 3-15, 4-15, 7-160

S_IFREG, 1-32, 3-15, 4-15,

4-27, 5-8, 7-161

S_IFSOCK, 3-15, 4-15,

7-161

S_IRGRP, 1-15, 4-27, 7-53

S_IROTH, 1-15, 4-27, 7-53

S_IRUSR, 1-14, 4-27, 7-53

S_IRWXG, 1-15, 3-16, 4-15,

4-27, 7-53, 7-161

S_IRWXO, 1-15, 3-16, 4-15,

4-27, 7-53, 7-161

S_IRWXU, 1-14, 3-16, 4-15,

4-27, 7-53, 7-161

S_ISGID, 1-14, 3-16, 4-15,

4-28, 7-161

S_ISUID, 1-14, 3-16, 4-15,

4-28, 7-161

S_ISVTX, 1-14, 1-32, 3-16,

4-15, 4-23, 4-28, 5-8,

7-161

S_IWGRP, 1-15, 4-28, 7-53

S_IWOTH, 1-15, 4-28, 7-53

S_IWUSR, 1-15, 4-28, 7-53

S_IXGRP, 1-15, 4-28, 7-53

S_IXOTH, 1-15, 4-28, 7-53

S_IXUSR, 1-15, 4-28, 7-53

Hewlett-Packard Company

Index

S_NONSTOP, 1-15, 1-32,

3-16, 4-15, 4-23,

4-28, 5-8, 7-161

SA_NOCLDSTOP, 7-62,

11-20

SCHAR_MAX, 11-12

SCHAR_MIN, 11-12

SEEK_CUR, 4-11

SEEK_END, 4-11

SEEK_SET, 4-11

SEM_UNDO, 7-19

SETALL, 7-12

SETVAL, 7-11

SHM_RDONLY, 7-45

SHM_RND, 7-45

SHRT_MAX, 11-12

SHRT_MIN, 11-12

SHUT_RD, 7-58

SHUT_RDWR, 7-58

SHUT_WR, 7-58

SIG_ABORT, 11-20

SIG_BLOCK, 7-65, 11-20

SIG_DEBUG, 11-20

SIG_DFL, 11-20

SIG_ERR, 11-20

SIG_IGN, 11-20

SIG_SETMASK, 7-65, 11-20

SIG_UNBLOCK, 7-65,

11-20

SIOCADDRT, 3-60

SIOCATMARK, 3-60

SIOCDARP, 3-61

SIOCDELRT, 3-60

SIOCGARP, 3-61

SIOCGIFADDR, 3-61

SIOCGIFBRDADDR, 3-61

SIOCGIFCONF, 3-61

SIOCGIFDSTADDR, 3-61

SIOCGIFFLAGS, 3-61

SIOCGIFNETMASK, 3-61

SIOCGIFNUM, 3-60

SIOCSARP, 3-61

SIOCSIFADDR, 3-61

SIOCSIFBRDADDR, 3-61

SIOCSIFDSTADDR, 3-61

SIOCSIFFLAGS, 3-61

SIOCSIFNETMASK, 3-61

SO_ACCEPTCONN, 3-52

SO_BROADCAST, 3-53,

7-39

Index

23

Index

24

SO_DEBUG, 3-53, 7-39

SO_DONTROUTE, 3-53,

7-39

SO_ERROR, 3-53

SO_KEEPALIVE, 3-53, 7-40

SO_LINGER, 1-26, 3-53,

7-40

SO_OOBINLINE, 3-53, 7-40

SO_RCVBUF, 3-53, 7-40

SO_REUSEADDR, 3-53,

7-40

SO_REUSEPORT, 3-53,

7-41

SO_SNDBUF, 3-54, 7-41

SO_TYPE, 3-54

SOCK_DGRAM, 3-54

SOCK_MAXBUF, 11-15

SOCK_STREAM, 3-54

SOL_SOCKET, 3-51, 7-37

SPAWN_NEWPGROUP,

8-44, 8-61

SPAWN_SETPGROUP,

8-44, 8-61

SPAWN_SETSIGDEF, 8-44,

8-61

SPAWN_SETSIGMASK,

8-44, 8-61

ST_NOSUID, 3-28, 7-174

ST_NOTRUNC, 3-28, 7-174

ST_RDONLY, 3-28, 7-174

STREAM_MAX, 11-15

TCIFLUSH, 11-55

TCIOFF, 11-55

TCIOFLUSH, 11-55

TCION, 11-55

TCOFLUSH, 11-55

TCOOFF, 11-55

TCOON, 11-55

TCSADRAIN, 11-55

TCSAFLUSH, 11-55

TCSANOW, 11-55

TIOCGWINSZ, 3-61

TIOCSWINSZ, 3-62

TOSTOP, 11-54

TZNAME_MAX, 11-12

UCHAR_MAX, 11-12

UINT_MAX, 11-12

ULLONG_MAX, 11-12

ULONG_MAX, 11-12

Hewlett-Packard Company

OSS System Calls Reference Manual

USHRT_MAX, 11-12

VEOF, 11-54

VEOL, 11-54

VERASE, 11-54

VINTR, 11-54

VKILL, 11-54

VQUIT, 11-55

VSTART, 11-55

VSTOP, 11-55

VSUSP, 11-55

WNOHANG, 10-8

WORD_BIT, 11-12

WUNTRACED, 10-8 symlink function, 7-178 to 7-181 system identifying, 9-5 limits, 11-8, 11-10 nodename, 9-5 system time, returning, 3-57 system time-zone, returning, 3-57

T tar file, 11-37 tar file format, 11-35 to 11-37 tdm_execve function, 8-2 to 8-15 tdm_execvep function, 8-16 to 8-29 tdm_fork function, 8-30 to 8-39 tdm_spawn function, 8-40 to 8-55 tdm_spawnp function, 8-56 to 8-71 termcap file, 11-38 to 11-50 terminal capability database, 11-38 terminal drivers, 11-57 terminal interface, 11-51, 11-57 termios file, 11-51 to 11-56 text file, executing, 2-4, 2-12, 2-20,

2-28, 2-36, 2-44, 8-4, 8-18,

8-42, 8-58 transport-provider process, 7-79, 7-81 default, 7-81 tty interface, 11-57 to 11-63

527186-003

U ulimit function, 9-2 to 9-3 umask function, 9-4 uname function, 9-5 to 9-6 unlink function, 9-7 to 9-10 user, getting scheduling priority, 3-47 user environment variables, 12-4 to

12-20 user ID returning effective, 3-36 returning real, 3-59 setting real and effective,

7-44 utime function, 9-11 to 9-13

V virtual addresses, specifying for shared memory, 7-45, 7-51 virtual memory, and shared memory segments, 7-45, 7-51

W wait function, 10-2 to 10-6 waitpid function, 10-7 to 10-12 write function, 10-13 to 10-17 writev function, 10-18 to 10-22

Index

527186-003 Hewlett-Packard Company Index

25

advertisement

Was this manual useful for you? Yes No
Thank you for your participation!

* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project

Related manuals

Download PDF

advertisement

Table of contents