Open System Services System Calls Reference Manual

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
Published
527186-003
N/A
July 2005
Contents
_____________________________
What is New in This Manual .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
xi
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
xi
Changed Functions .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
xii
.
.
.
.
.
.
.
.
.
.
.
.
.
.
xiii
New Functions
.
Changes in Miscellaneous Topics
Changes in Files
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
xiv
General Changes
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
xiv
About This Manual
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
xv
Audience .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
xvi
Purpose
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
xvi
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
xvi
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
xvi
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
xvii
Reference Section Numbers
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
xviii
Typographic and Keying Conventions
.
.
.
.
.
.
.
.
.
.
.
.
.
xix
.
Document Usage
Reference Page Format
Related Documents .
.
Section 1. System Functions (a - d)
accept . . . . . .
access . . . . . .
bind . . . . . .
chdir . . . . . .
chmod
. . . . .
chown
. . . . .
chroot . . . . . .
close . . . . . .
connect . . . . .
creat . . . . . .
dup
. . . . . .
dup2 . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
1-1
1-2
1-5
1-8
1-11
1-14
1-18
1-22
1-25
1-27
1-31
1-38
1-40
Section 2. System Functions (e)
exec . . . . .
execl . . . . .
execle . . . . .
execlp
. . . .
execv . . . . .
execve
. . . .
execvp
. . . .
_exit . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
2-1
2-2
2-3
2-11
2-19
2-27
2-35
2-43
2-51
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
3-1
Section 3. System Functions (f - i)
527186-003
.
.
.
.
.
.
.
.
.
Hewlett-Packard Company
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 . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
3-2
3-9
3-14
3-23
3-31
3-33
3-35
3-36
3-37
3-38
3-39
3-40
3-41
3-43
3-44
3-45
3-46
3-47
3-49
3-51
3-57
3-59
3-60
Section 4. System Functions (k - m)
kill
. . . . . .
link
. . . . . .
listen . . . . . .
lseek . . . . . .
lstat
. . . . . .
mkdir . . . . . .
mknod
. . . . .
msgctl
. . . . .
msgget
. . . . .
msgrcv
. . . . .
msgsnd . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
4-1
4-2
4-5
4-9
4-11
4-13
4-22
4-27
4-33
4-36
4-39
4-42
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
5-1
5-2
5-4
5-14
5-16
5-18
5-19
5-20
5-21
5-22
5-23
5-24
5-25
5-26
5-28
5-30
5-32
5-34
5-36
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
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
Contents
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 . . . .
527186-003
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
5-37
5-38
5-40
5-41
5-42
5-43
5-44
5-46
5-47
5-48
5-50
5-52
5-53
5-55
5-58
5-59
5-60
5-61
5-62
5-63
5-64
5-65
5-67
5-68
5-70
5-72
5-73
5-75
5-76
5-77
5-79
5-80
5-81
5-82
5-83
5-84
5-86
5-88
5-89
5-90
5-92
5-94
5-95
5-97
5-98
5-100
5-101
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
6-1
6-2
6-6
6-9
6-13
6-16
6-19
Hewlett-Packard Company
v
OSS System Calls Reference Manual
rename
. . .
rename_guardian
rename_oss . .
rmdir . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
6-23
6-24
6-26
6-32
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 . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
7-1
7-2
7-3
7-4
7-5
7-10
7-15
7-18
7-22
7-25
7-29
7-33
7-34
7-36
7-37
7-44
7-45
7-48
7-51
7-53
7-58
7-60
7-64
7-65
7-67
7-69
7-71
7-75
7-79
7-81
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-96
7-97
7-98
7-99
7-100
7-101
7-102
7-103
vi
.
.
.
.
.
.
.
.
Hewlett-Packard Company
527186-003
Contents
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
. . . . . . . .
527186-003
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Hewlett-Packard Company
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
7-104
7-105
7-106
7-107
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-132
7-133
7-135
7-136
7-137
7-138
7-139
7-140
7-141
7-142
7-143
7-144
7-145
7-146
7-147
7-148
7-149
7-150
7-151
7-152
7-153
7-154
7-155
7-156
7-157
7-158
7-159
7-169
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_ . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
7-178
7-182
7-183
7-184
7-185
7-186
7-187
7-190
7-191
7-194
7-197
Section 8. System Functions (t)
tdm_execve . . .
tdm_execvep
. .
tdm_fork . . . .
tdm_spawn . . .
tdm_spawnp . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
8-1
8-2
8-16
8-30
8-40
8-56
Section 9. System Functions (u)
ulimit . . . . .
umask . . . . .
uname
. . . .
unlink . . . . .
utime . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
9-1
9-2
9-4
9-5
9-7
9-11
Section 10. System Functions (w)
wait . . . . .
waitpid
. . . .
write . . . . .
writev . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
10-1
10-2
10-7
10-13
10-18
Section 11. Files .
ar . .
core .
cpio .
dir . .
float .
limits .
math .
null
.
saveabend
signal .
spthread.h
tar . .
termcap
termios
tty . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
11-1
11-2
11-3
11-4
11-7
11-8
11-10
11-17
11-18
11-19
11-20
11-27
11-35
11-38
11-51
11-57
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
12-1
12-2
12-4
12-21
12-29
12-36
12-38
12-39
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Section 12. Miscellaneous . . .
ascii . . . . . .
environ . . . . .
errno . . . . . .
filename . . . . .
hier
. . . . . .
pathname . . . . .
process_extension_results
viii
Hewlett-Packard Company
527186-003
Contents
Permuted Index
Index
.
527186-003
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Pindex-1
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Index-1
Hewlett-Packard Company
ix
OSS System Calls Reference Manual
LIST OF TABLES
Table 3−1. Ignored File Status Flags
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
3-3
Table 3−2. Guardian File Type Mappings
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
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
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
11-4
.
.
.
.
.
.
.
.
.
.
.
.
11-5
Table 11−2. cpio Archive File Filename Entry Format
Table 11−3. cpio Archive File Data Format .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
11-5
Table 11−4. cpio.h Header File Macros
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
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
.
.
.
.
.
.
.
.
.
.
.
.
12-2
.
.
.
.
.
.
.
.
.
.
.
.
12-3
.
Table 12−2. ASCII Character Set Hexadecimal Values
Table 12−3. ASCII Character Set Decimal Values .
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)
Added security group list information to resolve Genesis Change
Request 10-050106-4114. Added information for SIG_ABORT and
SIG_DEBUG.
execle(2)
Added security group list information to resolve Genesis Change
Request 10-050106-4114. Added information for SIG_ABORT and
SIG_DEBUG.
execlp(2)
Added security group list information to resolve Genesis Change
Request 10-050106-4114. Added information for SIG_ABORT and
SIG_DEBUG.
execv(2)
Added security group list information to resolve Genesis Change
Request 10-050106-4114. Added information for SIG_ABORT and
SIG_DEBUG.
execve(2)
Added security group list information to resolve Genesis Change
Request 10-050106-4114. Added information for SIG_ABORT and
SIG_DEBUG.
execvp(2)
Added security group list information to resolve Genesis Change
Request 10-050106-4114. Added information for SIG_ABORT and
SIG_DEBUG.
fork(2)
Added security group list information to resolve Genesis Change
Request 10-050106-4114.
fstat(2)
Added trust bit to possible values for file mode.
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)
527186-003
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.
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.
xvi
NAME
Function, file, or miscellaneous topic name and purpose.
LIBRARY
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.
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
Section
Content
Manual
___________________________________________________________________
(1)
User commands
OSS Shell and Utilities Reference Manual
(2)
System functions
OSS System Calls Reference Manual
(3)
Library functions
OSS Library Calls Reference Manual
OSS System Calls Reference Manual
(SPT_*( ) functions)
(4)
File formats and
data structures
OSS System Calls Reference Manual
OSS Library Calls Reference Manual
OSS Shell and Utilities Reference Manual
(5)
Miscellaneous topics and
environment variables
(6)
Games
OSS System Calls Reference Manual
OSS Library Calls Reference Manual
OSS Shell and Utilities Reference Manual
Not supplied by HP
(7)
Special files
OSS System Calls Reference Manual
(8)
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]
The function call was interrupted by a signal that was caught before a valid connection arrived.
[EINVAL]
The socket is not accepting connections.
[EMFILE]
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:
•
1−4
The errno value [ECONNRESET] can be returned when the transport-provider process
is unavailable.
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
Checks to see whether the file exists.
R_OK
Checks read permission.
W_OK
Checks write permission.
X_OK
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.
[EFAULT]
The path parameter points outside the process’s allocated address space.
[EFSBAD]
The program attempted an operation involving a fileset with a corrupted fileset
catalog.
[EINTR]
A signal was caught during execution of the function call.
[EINVAL]
The access_mode parameter contains an invalid bit pattern.
[EIO]
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)
[ENOENT]
[ENOROOT]
access(2)
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.
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:
•
527186-003
The errno values [EFAULT], [EFSBAD], [EINTR], [EIO], [ENOROOT], [ENXIO], and
[EOSSNOTRUNNING] can be returned.
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]
An input or output error occurred for an AF_UNIX socket.
[ELOOP]
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:
•
527186-003
A component of the pathname specified in the sockaddr structure does
not name an existing file.
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:
•
1−10
The errno value [ECONNRESET] can be returned when the transport provider process
is unavailable.
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]
The requested current working directory is not accessible because search permission is denied for a component of the pathname.
[EFAULT]
The path parameter is an invalid address.
[EFSBAD]
The fileset catalog for one of the filesets involved in the operation is corrupt.
[EIO]
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]
[ENOROOT]
1−12
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.
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.
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:
•
527186-003
The errno values [EFAULT], [EFSBAD], [EIO], [ENOROOT], [ENXIO],
[EOSSNOTRUNNING], and [EPERM] can be returned.
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>
#include <sys/stat.h>
/* optional except for POSIX.1 */
int chmod(
const char *path,
mode_t mode);
PARAMETERS
path
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.
mode
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:
1−14
S_ISUID
Sets the process’s effective user ID to the user ID of the file’s owner on execution.
S_ISGID
Sets the process’s effective group ID to the group ID of the file’s group on execution.
S_ISVTX
For a directory, permits modification to the directory only if the effective user ID
of the process matches that of the file being accessed.
S_IRWXU
Permits the file’s owner to read, write, and execute the file (or to search the directory).
S_IRUSR
Permits the file’s owner to read the file.
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
Permits the file’s group to read the file.
S_IWGRP
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:
S_TRUST
•
Disabling file system caching.
•
Returning control to a calling process only after the backup disk process
has received checkpoint data for a write operation.
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]
Search permission is denied for a component of the path parameter.
[EFAULT]
The path parameter points to a location outside of the allocated address space of
the process.
[EFSBAD]
The fileset catalog for one of the filesets involved in the operation is corrupt.
[EINVAL]
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.
[ELOOP]
Too many symbolic 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.
1−16
Hewlett-Packard Company
527186-003
System Functions (a - d)
[ENOENT]
[ENOROOT]
chmod(2)
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.
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]
The effective user ID does not match the user ID of the owner of the file, or the
owner does not have appropriate privileges.
[EROFS]
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:
527186-003
•
The errno values [EFAULT], [EFSBAD], [EINVAL], [ENOROOT], [ENXIO], and
[EOSSNOTRUNNING] can be returned.
•
The S_NONSTOP flag is supported for regular files.
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>
#include <unistd.h>
/* optional except for POSIX.1 */
int chown(
const char *path,
uid_t owner,
gid_t group);
PARAMETERS
path
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.
owner
Specifies a numeric value representing the owner ID.
group
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 [EINVAL].
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]
Search permission is denied on a component of the path parameter.
[EFAULT]
The path parameter is an invalid address.
[EFSBAD]
The fileset catalog for one of the filesets involved in the operation is corrupt.
[EINVAL]
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.
[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.
[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:
•
527186-003
The path parameter does not exist.
Hewlett-Packard Company
1−19
chown(2)
OSS System Calls Reference Manual
[ENOROOT]
•
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.
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]
The calling process does not have appropriate privileges.
[EROFS]
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:
1−20
•
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.
Hewlett-Packard Company
527186-003
System Functions (a - d)
chown(2)
HP extensions to the XPG4 Version 2 specification are:
•
527186-003
The errno values [EFAULT], [EFSBAD], [EIO], [ENOROOT], [ENXIO], and
[EOSSNOTRUNNING] can be returned.
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]
Search permission is denied for any component of the pathname.
[EFAULT]
The path parameter points outside the process’s allocated address space.
[EFSBAD]
The fileset catalog for one of the filesets involved in the operation is corrupt.
[EINVAL]
One of the following conditions exists:
[ELOOP]
•
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.
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:
•
1−24
The errno values [EFAULT], [EFSBAD], [EINVAL], [ENOROOT], [ENXIO], and
[EOSSNOTRUNNING] can be returned.
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:
•
1−26
The close( ) function can return the errno value [EISGUARDIAN].
Hewlett-Packard Company
527186-003
System Functions (a - d)
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:
527186-003
•
A connection is established
•
A timeout occurs
•
A signal is caught
Hewlett-Packard Company
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 [EALREADY].
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)
[EFAULT]
connect(2)
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]
The attempt to connect was interrupted by delivery of a signal. The connection
will be completed asynchronously.
[EINVAL]
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:
•
527186-003
A component of the pathname specified in the sockaddr structure does
not name an existing file.
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:
•
1−30
The errno value [ECONNRESET] can be returned when the transport-provider process
is unavailable.
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>
#include <sys/stat.h>
#include <fcntl.h>
/* optional except for POSIX.1 */
/* optional except for POSIX.1 */
int creat(
const char *path,
mode_t mode);
PARAMETERS
path
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.
mode
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 [EISDIR].
•
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:
[EFSBAD]
•
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.
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]
A signal was caught during the open operation. This value is returned only for
character special files (terminal devices) and for FIFO special files.
[EINVAL]
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.
[EIO]
A physical input or output error occurred. Data might have been lost during
transfer.
[EISDIR]
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]
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.
[ENOENT]
527186-003
One of these conditions exists:
•
The pathname prefix does not exist.
•
The path parameter points to an empty string.
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:
•
1−36
The group ID of the new file is determined by the value of the O_ISGID flag in the
parent directory.
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:
527186-003
•
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.
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]
1−38
The filedes parameter is not a valid open file descriptor.
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:
•
527186-003
The errno values [EISGUARDIAN] and [EWRONGID] can be returned.
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
Specifies an open file descriptor obtained from a successful call to the accept( ),
creat( ), dup( ), dup2( ), fcntl( ), open( ), pipe( ), socket( ), or socketpair( ) function.
new
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.
1−40
•
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
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:
•
527186-003
The errno values [EISGUARDIAN] and [EWRONGID] can be returned.
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
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 Process 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 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:
527186-003
•
OSS process ID (PID)
•
Parent process ID
•
Process group ID
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]
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.
[EACCES]
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, MAPPOOL space, stack space, or PFS space are temporarily inadequate.
[EFAULT]
An input address parameter is outside valid bounds limits.
[EINVAL]
The new process image file is a binary executable file with invalid attributes.
[ELOOP]
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:
2−8
•
The pathname pointed to by the path parameter
•
A component of the pathname pointed to by the path parameter
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:
527186-003
•
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.
Hewlett-Packard Company
2−9
execl(2)
OSS System Calls Reference Manual
The following are HP extensions to the XPG4 Version 2 specification:
2−10
•
Text files containing the #! interpreter_name [optional_string] header line can execute.
•
The [EINVAL], [ENODEV], [ENOTOSS], and [EUNKNOWN] error values are an
HP extension.
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 Process 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:
2−12
•
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.
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:
2−14
•
Priority
•
Processor on which the process executes
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]
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.
[EACCES]
One of the following conditions exists:
[EAGAIN]
2−16
•
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.
System resources such as disk space, process control block (PCB) space, MAPPOOL space, stack space, or PFS space are temporarily inadequate.
Hewlett-Packard Company
527186-003
System Functions (e)
execle(2)
[EFAULT]
An input address parameter is outside valid bounds limits.
[EINVAL]
The new process image file is a binary executable file with invalid attributes.
[ELOOP]
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:
2−18
•
Text files containing the #! interpreter_name [optional_string] header line can execute.
•
The [EINVAL], [ENODEV], [ENOTOSS], and [EUNKNOWN] error values are an
HP extension.
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
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 Process later in this reference page.
file
arg
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.
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:
2−22
•
Priority
•
Processor on which the process executes
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]
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.
[EACCES]
One of the following conditions exists:
[EAGAIN]
2−24
•
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.
System resources such as disk space, process control block (PCB) space, MAPPOOL space, stack space, or PFS space are temporarily inadequate.
Hewlett-Packard Company
527186-003
System Functions (e)
execlp(2)
[EFAULT]
An input address parameter is outside valid bounds limits.
[EINVAL]
The new process image file is a binary executable file with invalid attributes.
[ELOOP]
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:
2−26
•
Text files containing the #! interpreter_name [optional_string] header line can execute.
•
The [EINVAL], [ENODEV], [ENOTOSS], and [EUNKNOWN] error values are an HP
extension.
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
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 Process 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.
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 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:
527186-003
•
OSS process ID (PID)
•
Parent process ID
•
Process group ID
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]
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.
[EACCES]
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, MAPPOOL space, stack space, or PFS space are temporarily inadequate.
[EFAULT]
An input address parameter is outside valid bounds limits.
[EINVAL]
The new process image file is a binary executable file with invalid attributes.
[ELOOP]
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:
•
2−32
The pathname pointed to by the path parameter
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:
527186-003
•
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.
Hewlett-Packard Company
2−33
execv(2)
OSS System Calls Reference Manual
The following are HP extensions to the XPG4 Version 2 specification:
2−34
•
Text files containing the #! interpreter_name [optional_string] header line can execute.
•
The [EINVAL], [ENODEV], [ENOTOSS], and [EUNKNOWN] error values are an
HP extension.
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
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 Process 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.
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.
envp[ ]
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:
2−38
•
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
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.
•
527186-003
The creator access ID (CAID) is set to the process access ID (PAID) of the calling process.
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:
2−40
•
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]
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.
[EACCES]
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, MAPPOOL space, stack space, or PFS space are temporarily inadequate.
[EFAULT]
An input address parameter is outside valid bounds limits.
Hewlett-Packard Company
527186-003
System Functions (e)
execve(2)
[EINVAL]
The new process image file is a binary executable file with invalid attributes.
[ELOOP]
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), 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:
2−42
•
Text files containing the #! interpreter_name [optional_string] header line can execute.
•
The [EINVAL], [ENODEV], [ENOTOSS], and [EUNKNOWN] error values are an
HP extension.
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
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 Process later in this reference page.
file
argv[ ]
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.
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:
•
2−46
Priority
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]
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.
[EACCES]
One of the following conditions exists:
•
2−48
Search permission is denied for the directory components of the pathname prefix to the process image file.
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]
System resources such as disk space, process control block (PCB) space, MAPPOOL space, stack space, or PFS space are temporarily inadequate.
[EFAULT]
An input address parameter is outside valid bounds limits.
[EINVAL]
The new process image file is a binary executable file with invalid attributes.
[ELOOP]
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 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:
2−50
•
Text files containing the #! interpreter_name [optional_string] header line can execute.
•
The [EINVAL], [ENODEV], [ENOTOSS], and [EUNKNOWN] error values are an
HP extension.
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.
•
527186-003
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
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:
2−52
•
Open System Services currently does not support Common-Usage C.
•
Child processes of a terminated process are assigned a parent process ID of 1.
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>
#include <unistd.h>
#include <fcntl.h>
/* optional except for POSIX.1 */
/* optional except for POSIX.1 */
int fcntl(
int filedes,
int request
[ , int argument1 | , struct flock *argument2 ] );
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
request
Specifies the operation to be performed
argument1
Specifies a variable that depends on the value of the request parameter
argument2
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)
F_GETFD
fcntl(2)
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].
F_SETFD
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].
F_GETFL
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.
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 argument1 parameter. Some flags are ignored, depending on the file type, as listed:
Table 3−1. Ignored File Status Flags
File
type
Ignored file status flags
_ _____________________________________________
Directory
FIFO, pipe
Character special file
Regular file
Socket
O_APPEND, O_NONBLOCK,
O_SYNC
O_APPEND, O_SYNC
O_APPEND, O_SYNC
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
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:
F_SETOWN
•
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].
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
3−4
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
Returns a new file descriptor.
F_GETFD
Returns the value of the file descriptor flags. The return value is not negative.
F_GETFL
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
Returns the value 0 (zero).
F_SETFL
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]
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.
[EBADF]
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.
3−6
[EFAULT]
The argument2 parameter is an invalid address.
[EINTR]
The request parameter is F_SETLKW, and the fcntl( ) function was interrupted
by a signal that was caught.
[EINVAL]
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.
Hewlett-Packard Company
527186-003
System Functions (f - i)
[EIO]
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.
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:
•
3−8
The errno values [ECONNRESET], [EFAULT], [EIO], [EISGUARDIAN], [ENETDOWN], [ENOTOSS], and [EWRONGID] can be returned.
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>
#include <unistd.h>
/* optional except for POSIX.1 */
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-groupID 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:
527186-003
•
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.
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.
3−10
•
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)
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]
Open for execute access on the code file or any library file was denied.
[EAGAIN]
System resources such as disk space, process control block (PCB) space, MAPPOOL space, stack space, or PFS space are temporarily inadequate.
[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.
[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:
3−12
•
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.
Hewlett-Packard Company
527186-003
System Functions (f - i)
fork(2)
The following are HP extensions to the XPG4 Version 2 specification:
•
527186-003
The [EFAULT], [ENOTOSS], and [EUNKNOWN] error values are HP extensions.
Hewlett-Packard Company
3−13
fstat(2)
OSS System Calls Reference Manual
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>
#include <sys/stat.h>
/* optional except for POSIX.1 */
int fstat(
int filedes,
struct stat *buffer);
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.
buffer
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
ino_t
mode_t
nlink_t
char
uid_t
gid_t
char
dev_t
off_t
time_t
time_t
time_t
int64_t
};
st_dev;
st_ino;
st_mode;
st_nlink;
filler_1[2];
st_uid;
st_gid;
filler_2[4];
st_rdev;
st_size;
st_atime;
st_mtime;
st_ctime;
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
527186-003
System Functions (f - i)
fstat(2)
For
Contains
Regular file
Directory
Pipe or FIFO
AF_INET or AF_INET6 socket
AF_UNIX socket
ID of device containing directory entry
ID of device containing directory
ID of special fileset for pipes
ID of special fileset for sockets
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
st_ino
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
Pipe or FIFO
AF_INET or AF_INET6 socket
File serial number (unique)
File serial number (unique)
File serial number (unique)
File serial number (not unique within the
HP NonStop node)
File serial number of the socket file
(unique)
File serial number (unique)
File serial number (unique)
AF_UNIX socket
/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.
st_mode
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.
S_IFDIR
Directory.
S_IFIFO
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
527186-003
Hewlett-Packard Company
3−15
fstat(2)
OSS System Calls Reference Manual
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
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)
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.
st_nlink
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)
st_uid
fstat(2)
For
Contains
Regular file
Directory
FIFO
Pipe
AF_INET or AF_INET6 socket
AF_UNIX socket
/dev/null
/dev/tty
Number of links to the file
Number of links to the directory
Number of links to the file
-1
0 (zero)
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 next. Values for Guardian objects are
described in Use on Guardian Objects, later in this reference page.
st_gid
For
Contains
Regular file
Directory
Pipe or FIFO
AF_INET or AF_INET6 socket
AF_UNIX socket
/dev/null
/dev/tty
User ID of the file owner
User ID of the file owner
User ID of the file owner
User ID of the calling process
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.
st_rdev
For
Contains
Regular file
Directory
Pipe or FIFO
AF_INET or AF_INET6 socket
AF_UNIX socket
/dev/null
/dev/tty
Group ID of the file group
Group ID of the file group
Group ID of the file group
Group ID of the calling process
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
For
Contains
Regular file
Directory
Pipe or FIFO
AF_INET or AF_INET6 socket
AF_UNIX socket
/dev/null
/dev/tty
Undefined
Undefined
Undefined
0 (zero)
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.
st_atime
For
Contains
Regular file
Directory
Pipe or FIFO
AF_INET or AF_INET6 socket
AF_UNIX socket
/dev/null
/dev/tty
Size of the file in bytes
4096
0 (zero)
0 (zero)
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
Pipe or FIFO
AF_INET or AF_INET6 socket
Time of the last access
Time of the last access
Time of the last access
Value maintained in the socket data structure
Value retrieved from the inode
Current time
Composite value of the times of all openers
of the file
AF_UNIX socket
/dev/null
/dev/tty
For the /E entry of the local node, the value is the time of the most recent mounting of the root fileset.
st_mtime
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)
For
Contains
Regular file
Directory
Pipe or FIFO
AF_INET or AF_INET6 socket
Time of the last data modification
Time of the last modification
Time of the last data modification
Value maintained in the socket data structure
Value retrieved from the inode
Current time
Composite value of the times of all openers
of the file
AF_UNIX socket
/dev/null
/dev/tty
For the /E entry of the local node, the value is the time of the most recent mounting of the root fileset.
st_ctime
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
Pipe or FIFO
AF_INET or AF_INET6 socket
Time of the last file status change
Time of the last file status change
Time of the last file status change
Value maintained in the socket data structure
Value retrieved from the inode
Current time
Composite value of the times of all openers
of the file
AF_UNIX socket
/dev/null
/dev/tty
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
Guardian
st_mode
Example
in
/G
File
Type
File
Type
Permissions
___________________________________________________________________
/G
vol
vol/subvol
vol/subvol/fileid
vol/#123
ztnt
ztnt/#pty0001
vol1/zyq00001
N/A
Disk volume
Subvolume
Disk file
Temporary disk file
Subtype 30 process
Subtype 30 process
with qualifier
Subvolume
Directory
Directory
Directory
Regular file
Regular file
Directory
Character special
r-xr-xr-x
rwxrwxrwx
rwxrwxrwx
See following text
See following text
--x--x--x
rw-rw-rw-
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]
The filedes parameter is not a valid file descriptor.
[EFAULT]
The buffer parameter points to a location outside of the allocated address space
of the process.
[EFSBAD]
The program attempted an operation involving a fileset with a corrupted fileset
catalog.
[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.
[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:
•
3−22
The errno values [EFAULT], [EFSBAD], [EIO], [EISGUARDIAN], [ENETDOWN],
[ENOROOT], [ENXIO], and [EWRONGID] can be returned by the fstat( ) function.
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
Specifies an open file descriptor obtained from a successful call to the creat( ),
dup( ), dup2( ), fcntl( ), or open( ) function.
buffer
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
527186-003
Fileset block size:
Hewlett-Packard Company
3−23
fstatvfs(2)
f_frsize
f_blocks
OSS System Calls Reference Manual
For
Contains
Regular file
Directory
FIFO
/dev/null
Object in /G
/G
Terminal device file
/E
4096
4096
4096
4096
4096
4096
4096
4096
Fundamental file system block size:
For
Contains
Regular file
Directory
FIFO
/dev/null
Object in /G
/G
Terminal device file
/E
4096
4096
4096
4096
4096
4096
4096
4096
Total number of blocks in fileset, in units of f_frsize:
For
Contains
Regular file
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.
Number of blocks on the volume containing the object.
0
0
0
Directory
FIFO
/dev/null
Object in /G
/G
Terminal device file
/E
f_bfree
3−24
Total number of free blocks in fileset:
Hewlett-Packard Company
527186-003
System Functions (f - i)
fstatvfs(2)
For
Contains
Regular file
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
0
0
Directory
FIFO
/dev/null
Object in /G
/G
Terminal device file
/E
f_bavail
Number of free blocks available to a process without appropriate privileges:
For
Contains
Regular file
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
0
0
Directory
FIFO
/dev/null
Object in /G
/G
Terminal device file
/E
f_files
527186-003
Total number of file serial numbers (inode numbers) in the fileset:
Hewlett-Packard Company
3−25
fstatvfs(2)
f_ffree
OSS System Calls Reference Manual
For
Contains
Regular file
Directory
FIFO
/dev/null
Object in /G
/G
Terminal device file
/E
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.
The value of ULONG_MAX.
0
0
0
Total number of free file serial numbers (inode numbers) in the fileset:
For
Contains
Regular file
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.
The value of ULONG_MAX.
0
0
0
Directory
FIFO
/dev/null
Object in /G
/G
Terminal device file
/E
f_favail
Number of file serial numbers (inode numbers) available to a process without
appropriate privileges:
For
Contains
Regular file
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.
The value of ULONG_MAX.
0
0
0
Directory
FIFO
/dev/null
Object in /G
/G
Terminal device file
/E
3−26
Hewlett-Packard Company
527186-003
System Functions (f - i)
f_fsid
fstatvfs(2)
Fileset identifier:
For
Contains
Regular file
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.
Directory
FIFO
/dev/null
Object in /G
/G
Terminal device file
/E
f_basetype
f_flag
Type of file system:
For
Contains
Regular file
Directory
FIFO
/dev/null
Object in /G
/G
Terminal device file
/E
OSS
OSS
OSS
OSS
GUARDIAN
GUARDIAN
GUARDIAN
EXPAND
Bit mask indicating type of fileset access allowed:
For
Contains
Regular file
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.
2
3
Directory
FIFO
/dev/null
Object in /G
/G
527186-003
Hewlett-Packard Company
3−27
fstatvfs(2)
OSS System Calls Reference Manual
Terminal device file
/E
2
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
f_fstr
Maximum number of character bytes in a filename within the fileset:
For
Contains
Regular file
Directory
FIFO
/dev/null
Object in /G
/G
Terminal device file
/E
248
248
248
248
8
7
7
7
Fileset pathname prefix string:
For
Contains
Regular 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
Directory
FIFO
/dev/null
Object in /G
/G
Terminal device file
/E
3−28
Hewlett-Packard Company
527186-003
System Functions (f - i)
f_bminavail
f_bmaxavail
fstatvfs(2)
Number of blocks free on the disk volume with the least space remaining:
For
Contains
Regular file
Directory
FIFO
/dev/null
Object in /G
/G
Terminal device file
/E
Number of blocks.
Number of blocks.
Number of blocks.
Number of blocks.
Number of blocks.
0
0
0
Number of blocks free on the disk volume with the most space remaining:
For
Contains
Regular file
Directory
FIFO
/dev/null
Object in /G
/G
Terminal device file
/E
Number of blocks.
Number of blocks.
Number of blocks.
Number of blocks.
Number of blocks.
0
0
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]
The filedes parameter is not a valid file descriptor.
[EFAULT]
The buffer parameter points to an invalid address.
[EINTR]
The function was interrupted by a signal before any data arrived.
[EINVAL]
The file pointed to by the filedes parameter is an OSS pipe or a socket.
[EIO]
One of these conditions occurred:
527186-003
•
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.
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:
•
3−30
The errno values [EINVAL], [EISGUARDIAN], [ENETDOWN], and [EWRONGID]
can be returned.
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]
The filedes parameter is not a valid file descriptor.
[EINTR]
The fsync( ) function was interrupted by a signal that was caught.
[EINVAL]
The filedes parameter, although valid, does not refer to a file on which this operation is possible.
[EIO]
An I/O error occurred during a write to the fileset.
[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:
•
3−32
The errno values [EISGUARDIAN], [ENETDOWN], [ENXIO], and [EWRONGID] can
be returned.
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
Specifies the descriptor of a file that must be open for writing.
length
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]
The filedes parameter does not specify a valid file descriptor open for writing.
[EFBIG]
The new file size would exceed the process’s file size limit or the maximum file
size.
[EINTR]
The function was interrupted by a signal before any data arrived.
[EINVAL]
One of these conditions occurred:
527186-003
•
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).
Hewlett-Packard Company
3−33
ftruncate(2)
OSS System Calls Reference Manual
•
[EIO]
The value specified for the length parameter would cause the file to
exceed the file size limit for the calling process.
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:
•
3−34
The errno values [EISGUARDIAN], [ENETDOWN], and [EROFS] can be returned.
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>
#include <unistd.h>
/* optional except for POSIX.1 */
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>
#include <unistd.h>
/* optional except for POSIX.1 */
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>
#include <unistd.h>
/* optional except for POSIX.1 */
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
Specifies the number of entries that can be stored in the array pointed to by the
grouplist parameter.
grouplist
Points to the array in which the group list of the process is stored.
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.
[EINVAL]
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:
527186-003
•
The transport-provider process for this socket is no longer available.
•
The TCP/IP subsystem for this socket is no longer available.
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]
A user-supplied memory buffer cannot be accessed or written.
[EINVAL]
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:
•
3−42
The errno value [ECONNRESET] can be returned when the transport-provider process
is unavailable.
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]
The specified process is not in the same session as the calling process.
[ESRCH]
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:
•
527186-003
The function can return the errno value [ENOTOSS].
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>
#include <unistd.h>
/* optional except for POSIX.1 */
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>
#include <unistd.h>
/* optional except for POSIX.1 */
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>
#include <unistd.h>
/* optional except for POSIX.1 */
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:
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.
who
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]
527186-003
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.
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:
•
3−48
The function can return the errno value [ENOTOSS].
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]
527186-003
The socket parameter is not a valid file descriptor.
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:
•
3−50
The errno value [ECONNRESET] can be returned when the transport-provider process
is unavailable.
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
Specifies the file descriptor for the socket.
level
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:
•
527186-003
Between 0 and 255 to indicate the maximum number of
hops allowed.
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)
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.
527186-003
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
3−54
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.
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 setsockopt( ) 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]
A user-supplied memory buffer cannot be accessed or written.
[EINVAL]
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), setprotoent(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:
3−56
•
The errno value [ECONNRESET] can be returned when the transport provider process
is unavailable.
•
The SO_REUSEPORT option is supported.
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
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.
tzp
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
The number of whole seconds of elapsed time.
tv_usec
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:
3−58
•
This function returns errno values.
•
The behavior when the tzp parameter is a null pointer is specified.
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>
#include <unistd.h>
/* optional except for POSIX.1 */
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
Specifies the function to be performed for the tty device or socket.
arg
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
unsigned short
unsigned short
unsigned short
};
ws_row;
ws_col;
ws_xpixel;
ws_ypixel;
The winsize structure contains these fields:
ws_row
The number of rows, in characters, contained in the window
ws_col
The number of columns, in characters, contained in the window
ws_xpixel
The horizontal size, in pixels, of the window (zero if the size is not known or if
pixel values are not meaningful)
ws_ypixel
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]
The filedes parameter is not a valid descriptor.
[EFAULT]
The optional parameter is to be used as an address, but it points outside the process address space.
[EINTR]
A signal was caught during execution of the function.
[EINVAL]
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:
•
527186-003
The errno values [EFAULT], [ENETDOWN], [ENOTSUP], [ENXIO], [EOPNOTSUPP],
and [EWRONGID] can be returned.
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>
#include <signal.h>
/* optional except for POSIX.1 */
int kill(
pid_t pid,
int signal);
PARAMETERS
pid
Specifies the process or group of processes to be sent a signal.
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:
4−2
•
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.
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]
The process does not have permission to send the signal to any receiving process.
[ESRCH]
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:
4−4
•
Safeguard considerations
•
The ability to send signals to named processes
•
The error [ENOTOSS]
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
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.
path2
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]
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.
[EEXIST]
The link named by the path2 parameter already exists.
[EFAULT]
Either the path1 or path2 parameter is an invalid address.
[EFSBAD]
The fileset catalog for one of the filesets involved in the operation is corrupt.
[EINVAL]
The call attempted to create a link to a Guardian file (that is, a file in /G or in any
directory within /G).
[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.
[ELOOP]
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:
4−6
•
The pathname pointed to by the path1 parameter
•
The pathname pointed to by the path2 parameter
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]
[ENOROOT]
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.
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]
The requested link requires writing to a directory on a read-only fileset.
[EXDEV]
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:
•
4−8
The errors [EFAULT], [EFSBAD], [EINVAL], [EIO], [ENOROOT], [ENOTDIR],
[ENXIO], and [EOSSNOTRUNNING] can be returned.
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
Specifies the file descriptor for the socket.
backlog
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 backlog 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 TCPLISTEN-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:
4−10
•
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.
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>
#include <unistd.h>
/* optional except for POSIX.1 */
off_t lseek(
int filedes,
off_t offset,
int whence);
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.
offset
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.
whence
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]
527186-003
The filedes parameter is not an open file descriptor.
Hewlett-Packard Company
4−11
lseek(2)
OSS System Calls Reference Manual
[EINVAL]
[EISDIR]
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.
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:
•
4−12
The errno values [EINVAL], [EISDIR], [EISGUARDIAN], and [EWRONGID] can be
returned.
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
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.
buffer
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
ino_t
mode_t
nlink_t
char
uid_t
gid_t
char
dev_t
off_t
time_t
time_t
time_t
int64_t
};
st_dev;
st_ino;
st_mode;
st_nlink;
filler_1[2];
st_uid;
st_gid;
filler_2[4];
st_rdev;
st_size;
st_atime;
st_mtime;
st_ctime;
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.
For
Contains
Regular file
Directory
FIFO
AF_UNIX socket
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
st_ino
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
Contains
Regular file
Directory
FIFO
AF_UNIX socket
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)
st_mode
lstat(2)
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
Character special file.
S_IFDIR
Directory.
S_IFIFO
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
Owner class
S_ISGID
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.
st_nlink
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
For
Contains
Regular file
Directory
FIFO
AF_UNIX socket
/dev/null
/dev/tty
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.
st_gid
For
Contains
Regular file
Directory
FIFO
AF_UNIX socket
/dev/null
/dev/tty
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.
st_rdev
For
Contains
Regular file
Directory
FIFO
AF_UNIX socket
/dev/null
/dev/tty
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)
st_size
lstat(2)
For
Contains
Regular file
Directory
FIFO
AF_UNIX socket
/dev/null
/dev/tty
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.
st_atime
For
Contains
Regular file
Directory
FIFO
AF_UNIX socket
/dev/null
/dev/tty
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
Contains
Regular file
Directory
FIFO
AF_UNIX socket
/dev/null
/dev/tty
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.
st_mtime
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
For
Contains
Regular file
Directory
FIFO
AF_UNIX socket
/dev/null
/dev/tty
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.
st_ctime
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
Contains
Regular file
Directory
FIFO
AF_UNIX socket
/dev/null
/dev/tty
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
Guardian
st_mode
Example
in
/G
File
Type
File
Type
Permissions
___________________________________________________________________
/G
vol
vol/subvol
vol/subvol/fileid
vol/#123
ztnt
ztnt/#pty0001
vol1/zyq00001
N/A
Disk volume
Subvolume
Disk file
Temporary disk file
Subtype 30 process
Subtype 30 process
with qualifier
Subvolume
Directory
Directory
Directory
Regular file
Regular file
Directory
Character special
r-xr-xr-x
rwxrwxrwx
rwxrwxrwx
See following text
See following text
--x--x--x
rw-rw-rw-
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]
Search permission is denied for a component of the pathname pointed to by the
path parameter.
[EFAULT]
Either the buffer parameter or the path parameter points to a location outside of
the allocated address space of the process.
[EFSBAD]
The program attempted an operation involving a fileset with a corrupted fileset
catalog.
[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.
[ELOOP]
Too many symbolic links were encountered in translating path.
[ENAMETOOLONG]
One of the following is too long:
•
4−20
The pathname pointed to by the path parameter
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 [EOSSNOTRUNNING] 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>
#include <sys/stat.h>
/* optional except for POSIX.1 */
int mkdir(
const char *path,
mode_t mode);
PARAMETERS
path
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].
mode
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
Directory in the OSS file system or empty subvolume 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).
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:
•
527186-003
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.
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]
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.
[EEXIST]
The named file already exists.
[EFAULT]
The path parameter is an invalid address.
[EFSBAD]
The fileset catalog for one of the filesets involved in the operation is corrupt.
[EINVAL]
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]
4−24
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.
Hewlett-Packard Company
527186-003
System Functions (k - m)
mkdir(2)
•
[ENOROOT]
The path parameter specifies a file on a remote HP NonStop node but
communication with the remote node has been lost.
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]
[EROFS]
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.
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:
•
527186-003
The errno values [EFAULT], [EFSBAD], [EINVAL], [EIO], [ENOROOT], [ENXIO],
[EOSSNOTRUNNING], and [EPERM] can be returned.
Hewlett-Packard Company
4−25
mkdir(2)
4−26
OSS System Calls Reference Manual
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
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.
mode
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
The file is a character special file.
S_IFDIR
The file is a directory special file.
S_IFIFO
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:
527186-003
S_IRGRP
Read access by members of the group list
S_IROTH
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
Hewlett-Packard Company
4−27
mknod(2)
OSS System Calls Reference Manual
S_ISGID
Set the group ID of the file upon execution of the file
S_ISUID
Set the user ID of the file upon execution of the file
S_ISVTX
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
Write access by the owner of the file
S_IXGRP
Execute (search) access by members of the group list
S_IXOTH
Execute (search) access by others
S_IXUSR
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:
device
•
Disables file system caching
•
Returns control to a calling process only after the
backup disk process has received checkpoint data for a
write operation
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:
4−28
•
A file type as specified by the mode parameter.
•
An owner ID set to the effective user ID of the process.
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]
A component of the pathname prefix denies search permission, or write permission is denied on the parent directory of the file to be created.
[EEXIST]
The named file exists.
[EFAULT]
The path parameter points outside the process’s allocated address space.
[EFSBAD]
The fileset catalog for one of the filesets involved in the operation is corrupt.
[EINVAL]
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:
•
4−30
The named directory does not exist.
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]
[EROFS]
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.
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:
527186-003
•
The errno values [EFAULT], [EFSBAD], [ENOROOT], [ENXIO], and [EOSSNOTRUNNING] 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.
Hewlett-Packard Company
4−31
mknod(2)
OSS System Calls Reference Manual
•
4−32
Behavior is defined when values for the device parameter other than 0 (zero) are
specified.
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
Specifies the message queue identifier.
cmd
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
IPC_STAT
buf
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.
4−34
[EACCES]
The cmd parameter is IPC_STAT, but the calling process does not have read
permission.
[EFAULT]
The msqid_ds structure associated with the message queue identifier cannot be
found.
[EINVAL]
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.
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:
527186-003
•
The IPC_SETNONFT value for the cmd parameter is supported.
•
The errno values [EFAULT], [EMSGQNOTRUNNING], and [ENOTOSS] can be
returned.
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
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.
msgflg
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:
4−36
•
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).
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]
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.
[EEXIST]
A message queue identifier exists for the key parameter, and both IPC_CREAT
and IPC_EXCL are set.
[EFAULT]
The msqid_ds structure associated with the message queue identifier cannot be
found.
[EINVAL]
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:
•
4−38
The errno values [EFAULT], [EINVAL], [EMSGQNOTRUNNING], and [ENOTOSS]
can be returned.
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
Specifies the identifier of the message queue from which to read a message.
msgp
Specifies a pointer to the msgbuf structure that is to receive the message. (See
the NOTES section.)
msgsz
Specifies the maximum number of bytes allowed for the received message.
msgtyp
Specifies the message type to read from the queue.
msgflg
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]
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.
[EACCES]
The calling process does not have read permission for the specified message
queue.
[EFAULT]
The msqid_ds structure associated with the message queue identifier cannot be
found.
[EIDRM]
The message queue identified by the msqid parameter has been removed from
the system.
[EINTR]
The operation was interrupted by a signal.
[EINVAL]
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:
•
527186-003
The errno values [EFAULT], [EMSGQNOTRUNNING], and [ENOTOSS] can be
returned.
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
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.
msgp
Specifies a pointer to the msgbuf structure that contains the message. (See the
NOTES section.)
msgsz
Specifies the size of the data array in the msgbuf structure.
msgflg
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]
The calling process does not have the correct access permission for the operation.
[EAGAIN]
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.
[EFAULT]
The msqid_ds structure associated with the message queue identifier cannot be
found.
[EIDRM]
The message queue identified by the msqid parameter has been removed from
the system.
[EINTR]
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:
•
4−44
The errno values [EFAULT], [EMSGQNOTRUNNING], and [ENOTOSS] can be
returned.
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>
#include <sys/stat.h>
#include <fcntl.h>
/* optional except for POSIX.1 */
/* optional except for POSIX.1 */
int open(
const char *path,
int oflag
[ , mode_t mode ]);
PARAMETERS
path
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.
oflag
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.
mode
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)
O_EXCL
OSS System Calls Reference Manual
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:
•
5−6
For a static window, the open operation is always allowed; it finishes
when the connection is established.
Hewlett-Packard Company
527186-003
System Functions (n - p)
open(2)
•
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.
O_SYNC
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:
•
527186-003
If the O_NONBLOCK flag is not set, the open( ) function blocks until the device is
ready or available.
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:
[EFSBAD]
•
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.
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.
5−10
[EINTR]
A signal was caught during the open operation. This value is returned only for
character special files (terminal devices) and for FIFO special files.
[EINVAL]
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.
Hewlett-Packard Company
527186-003
System Functions (n - p)
[EIO]
open(2)
•
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.
[EISDIR]
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:
•
527186-003
The O_CREAT flag is not set, and the named file does not exist.
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:
527186-003
•
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.
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]
5−14
The filedes parameter is an invalid address.
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:
•
527186-003
The errno values [EFAULT], [ENOROOT], and [EOSSNOTRUNNING] can be
returned.
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
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.
parent
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( ).
child
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
specifies the address of the thread attributes object whose detachstate attribute
is obtained.
detachstate
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 Services 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
Successful completion.
[EINVAL]
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.
guardsize
receives the value of the guardsize attribute.
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
Successful completion.
[EINVAL]
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:
•
5−20
IEEE Std 1003.1c-1995, POSIX System Application Program Interface
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
Successful completion.
[EINVAL]
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
specifies the address of the thread attributes object with the scheduling policy
attribute whose scheduling parameters are obtained.
param
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 Services 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
Successful completion.
[EINVAL]
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
specifies the address of the thread attributes object whose scheduling policy
attribute is obtained.
policy
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 Services 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
Successful completion.
[EINVAL]
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
Specifies the address of the thread attributes object whose stack address attribute
is obtained.
stackaddr
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
specifies the address of the thread attributes object whose stacksize attribute is
obtained.
stacksize
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
Successful completion.
[EINVAL]
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
Successful completion.
[EINVAL]
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
specifies the thread attributes object whose detachstate attribute is to be set.
detachstate
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:
5−28
0
Successful completion.
[EINVAL]
The value specified by the attr parameter is not a valid thread attributes object or
the detachstate parameter is invalid.
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
specifies the address of the thread attributes object whose guardsize attribute is
to be set.
guardsize
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 guardsize 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
5−30
Successful completion.
Hewlett-Packard Company
527186-003
System Functions (n - p)
[EINVAL]
pthread_attr_setguardsize_np(2)
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:
•
527186-003
IEEE Std 1003.1c-1995, POSIX System Application Program Interface
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:
5−32
0
Successful completion.
[EINVAL]
The value specified by the attr parameter is not a valid thread attributes object or
the inheritsched parameter contains an invalid value.
Hewlett-Packard Company
527186-003
System Functions (n - p)
[ENOTSUP]
pthread_attr_setinheritsched(2)
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
specifies the address of the thread attributes object with the scheduling policy
attribute whose scheduling parameters are to be set.
param
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
Successful completion.
[EINVAL]
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
specifies the address of the thread attributes object whose scheduling policy
attribute is to be set.
policy
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
specifies the address of the thread attributes object whose stacksize attribute is
to be set.
stacksize
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
Successful completion.
[EINVAL]
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:
5−38
0
Successful completion.
[ESRCH]
The value of the thread parameter does not specify an existing thread.
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
specifies the routine to be executed as the cleanup handler.
arg
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
Successful completion.
[EINVAL]
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
Successful completion.
[EBUSY]
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.
[EINVAL]
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
specifies the condition variable to be initialized.
attr
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:
5−44
0
Successful completion.
[EAGAIN]
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.
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:
•
527186-003
IEEE Std 1003.1c-1995, POSIX System Application Program Interface
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
specifies the condition variable that the calling thread waits on.
mutex
specifies the mutex associated with the condition variable specified by the cond
parameter.
abstime
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 System 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 abstime 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
Successful completion.
[EINVAL]
One of the following conditions exists:
[ENOMEM]
•
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.
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
specifies the condition variable that the calling thread waits on.
mutex
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
5−50
Successful completion.
Hewlett-Packard Company
527186-003
System Functions (n - p)
[EINVAL]
[ENOMEM]
pthread_cond_wait(2)
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.
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
Successful completion.
[EINVAL]
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:
•
527186-003
IEEE Std 1003.1c-1995, POSIX System Application Program Interface
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
specifies the location to receive the identifier for the thread being created.
attr
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
Successful completion.
[EAGAIN]
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.
[EINVAL]
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
is an integral number of seconds.
tv_nsec
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
Successful completion.
[EINVAL]
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:
•
5−58
IEEE Std 1003.1c-1995, POSIX System Application Program Interface
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
Successful completion.
[EINVAL]
The thread parameter does not specify a joinable thread.
[ESRCH]
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
specifies the first thread identifier to be compared.
t2
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
The t1 and t2 parameters do not designate the same object.
Nonzero
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
specifies the number of seconds and nanoseconds to add to the current system
time to determine an expiration time.
abstime
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
is an integral number of seconds.
tv_nsec
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:
•
5−62
IEEE Std 1003.1c-1995, POSIX System Application Program Interface
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
Specifies the thread for which you want the attribute object.
attr_p
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:
Con Levl
Minimum Scheduled Quantum
---------
-----------------------
0
Infinity
1
1 second
2
0.5 seconds
...
...
10
0.1 seconds
...
...
100
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
specifies the thread whose scheduling policy and parameters are obtained.
policy
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.
param
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
Successful completion.
[ESRCH]
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
specifies the thread whose termination is awaited by the calling thread.
value_ptr
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]
The thread parameter does not specify a joinable thread.
[ESRCH]
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
specifies the location where the new thread-specific data key is to be stored.
destructor
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 nonNULL 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
Successful completion.
[EAGAIN]
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
Successful completion.
[EINVAL]
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
specifies the thread to receive the signal.
sig
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 Services 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 signal( ) 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
Successful completion.
[EINVAL]
The value of the sig parameter is invalid or specifies an unsupported signal.
[ESRCH]
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:
•
527186-003
IEEE Std 1003.1c-1995, POSIX System Application Program Interface
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
Successful completion.
[EBUSY]
An attempt was made to destroy the mutex indicated by the mutex parameter
while it is locked or referenced.
[EINVAL]
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
specifies the mutex to be initialized.
attr
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
Successful completion.
[EAGAIN]
The system lacks the necessary resources to initialize the mutex.
[EBUSY]
The system detected an attempt to reinitialize a mutex (an attempt to initialize a
previously initialized but not yet destroyed mutex).
[EINVAL]
The value specified by the attr parameter is invalid.
[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
Successful completion.
[EBUSY]
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
Successful completion.
[EINVAL]
The value specified for the mutex parameter is invalid.
[EPERM]
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
Successful completion.
[EINVAL]
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
Successful completion.
[EINVAL]
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:
•
527186-003
IEEE Std 1003.1c-1995, POSIX System Application Program Interface
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
specifies the mutex attributes object whose mutex type attribute is to be
modified.
kind
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:
5−86
0
Successful completion.
[EINVAL]
The value specified by the attr parameter is invalid.
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:
•
527186-003
IEEE Std 1003.1c-1995, POSIX System Application Program Interface
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
Successful completion.
[EINVAL]
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
specifies the new cancelability state for the calling thread. Valid values are:
PTHREAD_CANCEL_ENABLE
PTHREAD_CANCEL_DISABLE
oldstate
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
Successful completion.
[EINVAL]
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
oldtype
receives the previous cancelability type for the calling thread.
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
Successful completion.
[EINVAL]
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:
Con Levl
Minimum Scheduled Quantum
---------
----------------------------
0
Infinity
1
1 second
2
0.5 seconds
...
...
10
0.1 seconds
...
...
100
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]
The value specified by new_level is negative.
[EAGAIN]
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
specifies the thread whose scheduling policy and parameters are to be set.
policy
specifies the new scheduling policy value for the thread specified by the thread
parameter. Valid values are:
SCHED_FIFO
param
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
527186-003
Successful completion.
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
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.
value
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:
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.
set
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.
oset
receives the value of the current signal mask (unless this value is NULL).
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:
5−98
0
Successful completion.
[EINVAL]
The value specified for the how parameter is invalid.
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
Successful completion.
[EPERM]
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:
•
527186-003
IEEE Std 1003.1c-1995, POSIX System Application Program Interface
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)
OSS System Calls Reference Manual
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>
#include <unistd.h>
/* optional except for POSIX.1 */
ssize_t read(
int filedes,
void *buffer,
size_t nbytes);
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.
buffer
Points to the buffer to receive data read.
nbytes
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
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]
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.
[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 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]
The value of the nbytes parameter is greater than SSIZE_MAX.
[EIO]
One of these conditions occurred:
[EISDIR]
•
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.
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:
•
6−4
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.
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:
•
527186-003
The errno values [ECONNRESET], [EFAULT], [EFILEBAD], [EINVAL], [EISDIR],
[EISGUARDIAN], [ENETDOWN], [ENOTCONN], [ETIMEDOUT], and [EWRONGID] can be returned.
Hewlett-Packard Company
6−5
readlink(2)
OSS System Calls Reference Manual
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
Specifies the pathname of the destination file or directory.
buffer
Points to the user’s buffer. The buffer should be at least as large as the buf_size
parameter.
buf_size
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:
•
6−6
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.
Hewlett-Packard Company
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.
[EFAULT]
The path parameter points outside the process’s allocated address space.
[EFSBAD]
The fileset catalog for one of the filesets involved in the operation is corrupt.
[EINVAL]
The file named by the path parameter is not a symbolic link.
[EIO]
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:
•
527186-003
A device was specified that does not exist, or a request was made beyond
the limits of the device.
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:
•
6−8
The errno values [EFAULT], [EFSBAD], [ENOROOT], [ENXIO], and [EOSSNOTRUNNING] can be returned.
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
Specifies an open file descriptor obtained from a successful call to the accept( ),
creat( ), dup( ), dup2( ), fcntl( ), open( ), pipe( ), socket( ), or socketpair( ) function.
iov
Points to an iovec structure that identifies the buffers into which the data is to be
placed.
iov_count
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):
527186-003
•
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:
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
int
iov_base;
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]
[EBADF]
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.
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]
A readv( ) operation was interrupted by a signal before any data arrived.
[EINVAL]
One of these conditions occurred:
[EIO]
[EISDIR]
•
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.
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.
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:
•
6−12
The errno values [ECONNRESET], [EFAULT], [EFILEBAD], [EINVAL], [EISDIR],
[EISGUARDIAN], [ENETDOWN], [ENOTCONN], [ETIMEDOUT], and [EWRONGID] can be returned.
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
Specifies the file descriptor of the socket.
buffer
Points to the buffer where the message should be written.
length
Specifies the length in bytes of the buffer pointed to by the buffer parameter.
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 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]
A user-supplied memory buffer cannot be accessed or written.
[EINTR]
A signal interrupted the function before any data was available.
[EINVAL]
The MSG_OOB value is specified in the flags parameter and no out-of-band
data is available.
[EIO]
An input or output error occurred.
[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), shutdown(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:
•
6−14
The errno value [ECONNRESET] can be returned when the transport-provider process
is unavailable.
Hewlett-Packard Company
527186-003
System Functions (r)
527186-003
recv(2)
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
Specifies the file descriptor of the socket.
buffer
Points to the buffer where the message should be written.
length
Specifies the length in bytes of the buffer pointed to by the buffer parameter.
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:
address
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.
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]
A user-supplied memory buffer cannot be accessed or written.
[EINTR]
A signal interrupted the function before any data was available.
[EINVAL]
The MSG_OOB value is specified in the flags parameter and no out-of-band
data is available.
[EIO]
An input or output error occurred.
[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), shutdown(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:
•
6−18
The errno value [ECONNRESET] can be returned when the transport-provider process
is not available.
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
Specifies the file descriptor of the socket.
message
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]
6−20
The socket parameter is not a valid file descriptor.
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]
A signal interrupted the function before any data was available.
[EINVAL]
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]
An input or output error occurred.
[EMFILE]
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:
6−22
•
The errno value [ECONNRESET] can be returned when the transport-provider process
is not available.
•
The errno value [EMFILE] can be returned.
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
Specifies the current Guardian filename of the file to be renamed.
to
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
Identifies the file or directory to be renamed.
to
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:
— The file owner
— The directory owner
— A process with appropriate privileges
[EBUSY]
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]
The to parameter specifies an existing nonempty directory or an existing Guardian file (a file in /G).
[EFAULT]
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]
The to parameter specifies a directory and the from parameter specifies a
filename that is not a directory.
[ELOOP]
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]
527186-003
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.
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:
6−30
•
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.
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:
— The parent directory owner
— The directory owner
— A process with appropriate privileges
[EBUSY]
[EFAULT]
527186-003
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.
Hewlett-Packard Company
6−33
rmdir(2)
OSS System Calls Reference Manual
[EFSBAD]
The fileset catalog for one of the filesets involved in the operation is corrupt.
[EINVAL]
The specified . (dot) or . . (dot-dot) pathname cannot be removed.
[EIO]
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]
[ENOROOT]
[ENOTDIR]
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.
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.
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]
6−34
The directory specified by the path parameter resides on a read-only fileset.
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:
•
527186-003
The errno values [EFAULT], [EFSBAD], [EINVAL], [ENOROOT], [ENOTEMPTY],
[ENXIO], and [EOSSNOTRUNNING] can be returned.
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
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.
readfds
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.
writefds
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.
errorfds
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.
timeout
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
completion of the call.
fd
Specifies a file descriptor.
fdset
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]
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.
[EINTR]
A signal was delivered before the time limit specified by the timeout parameter
expired and before any of the selected events occurred.
[EINVAL]
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
Specifies the number of the semaphore to be processed.
cmd
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
Contains the semaphore value to which the semval field of the
sem structure is set when the cmd parameter has the value SETVAL. Individual semaphores are defined using the sem structure, where semval is one of the structure’s fields.
*buf
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)
*array
semctl(2)
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.
arg
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
Returns the OSS process ID of the process that last operated on the specified
semaphore. This operation requires read access permission.
GETVAL
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
527186-003
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.
Hewlett-Packard Company
7−11
|
|
|
|
semctl(2)
SETALL
OSS System Calls Reference Manual
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:
IPC_STAT
•
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.
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
7−12
Returns the value of the semncnt field from the semid_ds structure.
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]
The calling process does not have the required read or alter access.
[EFAULT]
One of the following is true:
[EINVAL]
•
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.
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:
[ERANGE]
527186-003
•
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.
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.
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:
•
7−14
The errno values [EFAULT] and [ENOTOSS] can be returned.
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
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.
nsems
Specifies the number of OSS semaphores to create in the semaphore set.
semflg
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:
527186-003
•
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.
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]
7−16
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.
Hewlett-Packard Company
527186-003
System Functions (s and S)
semget(2)
[EEXIST]
A semaphore set ID already exists for the key parameter, but ((semflg &
IPC_CREAT) && (semflg & IPC_EXCL)) is not equal to 0 (zero).
[EINVAL]
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:
•
527186-003
The errno value [ENOTOSS] can be returned.
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
Specifies the ID of the semaphore set.
sops
Points to the user-defined array of sembuf structures that contain the semaphore
operations.
nsops
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
sem_op;
short int
sem_flg;
};
The fields in the sembuf structure are defined as follows:
7−18
sem_num
Specifies an individual semaphore within the semaphore set.
sem_op
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.
Hewlett-Packard Company
527186-003
System Functions (s and S)
sem_flg
semop(2)
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:
7−20
[E2BIG]
The value of the nsops parameter is greater than the system-defined maximum.
[EACCES]
The calling process does not have the required access permission.
[EAGAIN]
The value of (sem_flg && IPC_NOWAIT) is TRUE, but the requested operation would cause the calling process to be suspended.
[EFAULT]
The address used for the sops parameter is invalid.
[EFBIG]
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.
[EIDRM]
The semaphore set ID specified by the semid parameter was removed from the
system while the process was waiting for it.
[EINTR]
The semop( ) function was interrupted by a signal.
Hewlett-Packard Company
527186-003
System Functions (s and S)
[EINVAL]
[ENOSPC]
semop(2)
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.
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:
•
527186-003
The errno values [EFAULT] and [ENOTOSS] can be returned.
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
Specifies the file descriptor of the socket.
buffer
Points to the buffer containing the message to send.
length
Specifies the length in bytes of the message to send.
flags
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]
A signal interrupted the function before any data was transmitted.
[EIO]
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]
527186-003
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.
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:
•
7−24
The errno value [ECONNRESET] can be returned when the transport-provider process
is not available.
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
Specifies the file descriptor of the socket.
message
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]
A user-supplied memory buffer cannot be accessed.
[EINTR]
A signal interrupted the function before any data was transmitted.
[EINVAL]
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]
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.
[ELOOP]
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:
527186-003
•
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.
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 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), sendto(2), setsockopt(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:
7−28
•
The errno value [ECONNRESET] can be returned when the transport-provider process
is not available.
•
The errno value [ENOPROTOOPT] can be returned.
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
Specifies the file descriptor of the socket.
message
Points to the buffer containing the message to be sent.
length
Specifies the length in bytes of the message to be sent.
flags
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
dest_addr
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:
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.
dest_len
527186-003
Specifies the length of the sockaddr structure pointed to by the dest_addr
parameter.
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]
A signal interrupted the function before any data was transmitted.
[EIO]
The socket is in the AF_UNIX domain and an input or output error occurred.
[EINVAL]
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:
[ENOMEM]
•
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.
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:
•
7−32
The errno value [ECONNRESET] can be returned when the transport-provider process
is not available.
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>
#include <unistd.h>
/* Optional except for POSIX.1 */
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]
The value of the gid parameter is invalid or out of range.
[EPERM]
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:
•
527186-003
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.
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>
#include <unistd.h>
/* optional except for POSIX.1 */
int setpgid(
pid_t pid,
pid_t pgid);
PARAMETERS
pid
Specifies the process whose process group ID is to be changed.
pgid
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]
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.
[EINVAL]
One of the following conditions exists:
[ENOTOSS]
7−34
•
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.
The calling process is not an OSS process. The requested operation is not supported from the Guardian environment.
Hewlett-Packard Company
527186-003
System Functions (s and S)
[EPERM]
[ESRCH]
setpgid(2)
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:
•
527186-003
The errno value [ENOTOSS] can be returned.
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>
#include <unistd.h>
/* optional except for POSIX.1 */
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:
•
7−36
The errno value [ENOTOSS] can be returned.
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
Specifies the file descriptor for the socket.
level
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)
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 [ENOPROTOOPT].
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.
527186-003
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]
A user-supplied memory buffer cannot be accessed.
[EINVAL]
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), setprotoent(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:
527186-003
•
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.
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>
#include <unistd.h>
/* optional except for POSIX.1 */
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]
The uid parameter is out of range.
[EPERM]
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
Specifies the identifier for the shared memory segment. The identifier is usually
returned by a previous call to the shmget( ) function.
shmaddr
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.
shmflag
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 [ENOTOSS].
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]
7−46
The calling process does not have access permission for the requested operation.
Hewlett-Packard Company
527186-003
System Functions (s and S)
[EINVAL]
shmat(2)
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:
[ENOTOSS]
•
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).
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:
•
527186-003
The errno value [ENOTOSS] can be returned.
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
Specifies the shared memory identifier for the segment.
cmd
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
buf
7−48
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.
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 [ENOTOSS].
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]
The cmd parameter is IPC_STAT, but the calling process does not have read
permission.
[EFAULT]
One of the following conditions exists:
•
527186-003
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.
Hewlett-Packard Company
7−49
shmctl(2)
OSS System Calls Reference Manual
•
[EINVAL]
The cmd parameter is IPC_SET, and the buf structure is not in the
address space of the process.
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:
•
7−50
The errno values [EFAULT] and [ENOTOSS] can be returned.
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 [ENOTOSS].
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:
•
7−52
The errno value [ENOTOSS] can be returned.
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
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.
size
Specifies the minimum number of bytes to allocate for the shared memory segment.
shmflag
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:
7−54
•
It identifies a specific entry in the system-maintained shared memory table.
•
It allows detection of references to a previously removed shared memory identifier.
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 [ENOTOSS].
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:
7−56
[EACCES]
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.
[EEXIST]
A shared memory identifier already exists for the key parameter, but
IPC_CREAT and IPC_EXCL were both set in the shmflag parameter.
[EINVAL]
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.
Hewlett-Packard Company
527186-003
System Functions (s and S)
shmget(2)
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:
•
527186-003
The errno value [ENOTOSS] can be returned.
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
Specifies the file descriptor of the socket.
how
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.
7−58
[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.
Hewlett-Packard Company
527186-003
System Functions (s and S)
[ENOMEM]
shutdown(2)
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:
•
527186-003
The errno value [ECONNRESET] can be returned.
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
Specifies the signal. The signal names are defined in the signal.h header file.
The range of valid signals depends on the requested action.
action
Points to a sigaction structure that describes the action to be taken upon receipt
of the signal identified by the signal parameter.
o_action
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]
The action or o_action parameter points to a location outside of the allocated
address space of the process.
[EINVAL]
One of the following conditions exists:
[ENOTOSS]
•
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.
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), sigsuspend(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), sigprocmask(2).
Files: signal(4).
STANDARDS CONFORMANCE
The following are HP extensions to the XPG4 Version 2 specification:
•
7−64
The [EFAULT] and [ENOTOSS] errors can be returned.
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:
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.
set
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.
o_set
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 SIGINT 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 sigprocmask( ) 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.
[EINVAL]
The value of the how parameter is not equal to one of the defined values.
[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), sigemptyset(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:
7−66
•
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].
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:
7−68
•
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.
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)
OSS System Calls Reference Manual
RELATED INFORMATION
Functions: recv(2), recvmsg(2), socket(2).
STANDARDS CONFORMANCE
This function is an extension to the XPG4 specification.
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
Specifies the address family of the communications domain in which the socket
is to be created.
type
Specifies the type of socket to be created.
protocol
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 protocol, 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
0x28000000
0x30000000
0x38000000
0x40000000
0x48000000
0x22000000
0x2A000000
0x32000000
0x3A000000
0x42000000
0x4A000000
0x24000000
0x2C000000
0x34000000
0x3C000000
0x44000000
0x4C000000
0x26000000
0x2E000000
0x36000000
0x3E000000
0x46000000
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]
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.
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), shutdown(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:
•
7−74
The errno values [EDEFINEERR], [ENOENT], and [ETANOTRUNNING] can be
returned.
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
Specifies the communications domain in which the sockets are created. This
parameter must be set to AF_UNIX.
type
Specifies the type of sockets to create.
protocol
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
0x28000000
0x30000000
0x38000000
0x40000000
0x48000000
0x22000000
0x2A000000
0x32000000
0x3A000000
0x42000000
0x4A000000
0x24000000
0x2C000000
0x34000000
0x3C000000
0x44000000
0x4C000000
0x26000000
0x2E000000
0x36000000
0x3E000000
0x46000000
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]
A user-supplied memory buffer cannot be accessed or written.
[EMFILE]
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:
•
7−78
The errno values [ENOENT] and [ETANOTRUNNING] can be returned.
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:
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
buffer
Points to the buffer to contain the null-terminated transport-provider process
name.
maxlen
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:
527186-003
•
An OSS transport agent process (one per processor)
•
A domain-specific transport-provider process (one or more per node)
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]
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 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
Specifies tag being waited on
timelimit
Specifies how many hundredths of a second to wait for a completed I/O:
-1
means wait forever
0
means immediate return
count_transferred
Specifies transfer count of completed I/O; set by callback when SPT_SUCCESS
is returned.
error
Specifies Guardian error number for I/O; set by callback when SPT_SUCCESS
is returned or as described in ERRORS
userdata
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
filenum is not registered.
29
filenum < 0 (zero).
40
timelimit has expired.
[EINTR]
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
Specifies an OSS file descriptor.
timeout
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]
A signal was received via pthread_kill( ) and is not blocked, ignored, or handled.
[EINVAL]
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
Specifies an OSS file descriptor.
timeout
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]
Invalid function argument.
[EBADF]
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 Reference 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 Reference 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 Reference 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
Specifies Guardian file number whose IO has completed
tag
Specifies tag of completed IO
count_transferred
Specifies transfer count of completed IO
error
Specifies Guardian error number for completed IO
userdata
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 Reference 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 Reference 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 Reference 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 Reference 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 Reference 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
$RECEIVE was successfully registered.
29
$RECEIVE was already registered prior to this call.
29
FILE_COMPLETE_SET_( ) addition of $RECEIVE returned nonzero.
29
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
Specifies the Guardian file number for thev file whose awaiting I/O is to be interrupted.
errorSPT
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
- SPT_ERROR
40
- SPT_TIMEOUT
[EINTR]
- 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
Specifies the Guardian file number for the file whose awaiting I/O is to be interrupted
tag
Specifies tag whose awaiting I/O is to be interrupted
error_SPT
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
SPT_ERROR
40
SPT_TIMEDOUT
EINTR
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
Specifies OSS file descriptor of interest
read
Specifies file descriptor is read ready
write
Specifies file descriptor is write ready
error
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 Reference 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 Reference 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 Reference 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
Specifies the Guardian file number for $RECEIVE (always 0)
buffer
Specifies the data buffer
read_count
Specifies the number of bytes to read
count_read
Specifies the number of bytes read
timelimit
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:
•
7−124
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.
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
Specifies the Guardian file number for the file being registered
functionPtr
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
Specifies the OSS file descriptor being registered
functionPtr
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
Specifies the Pathsend tag that should be registered.
callback
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. */
);
userdata
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
Specifies the OSS file descriptor for the file of interest
read
Nonzero indicates interest in read ready
write
Nonzero indicates interest in write ready
error
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)
The thread was suspended for the full time specified.
seconds
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
Callback has readied a thread to run, and will be invoked again
as soon as possible.
-1
Callback has not readied a thread, but will be invoked again as
soon as possible.
>0 (zero)
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)
Successful completion of the call. The current active transaction
handle is returned in tx_handle.
22
A bounds error occurred.
29
There are missing parameters.
75
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)
Indicates the transaction handle was successfully set.
22
Indicates that a bounds error occurred.
29
Indicates missing parameters.
75
Indicates that there is no current transaction.
78
Indicates an invalid transaction identifier or that a transaction
has not started on this Expand node.
715
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]
A pthread_kill( ) function call received a signal that is not
blocked, ignored, or handled.
[EINVAL]
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
Specifies the Guardian file number being waited on
tag
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>
#include <sys/stat.h>
/* optional except for POSIX.1 */
int stat(
const char *path,
struct stat *buffer);
PARAMETERS
path
Points to the pathname identifying the file.
buffer
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
ino_t
mode_t
nlink_t
char
uid_t
gid_t
char
dev_t
off_t
time_t
time_t
time_t
int64_t
};
st_dev;
st_ino;
st_mode;
st_nlink;
filler_1[2];
st_uid;
st_gid;
filler_2[4];
st_rdev;
st_size;
st_atime;
st_mtime;
st_ctime;
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.
For
Contains
Regular file
Directory
FIFO
AF_UNIX socket
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
st_ino
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
FIFO
AF_UNIX socket
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.
st_mode
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
7−160
Hewlett-Packard Company
Character special file.
527186-003
System Functions (s and S)
stat(2)
S_IFDIR
Directory.
S_IFIFO
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_IRWXG
Group class
S_IRWXO
Other class
S_IRWXU
Owner class
S_ISGID
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)
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
527186-003
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).
Hewlett-Packard Company
7−161
|
|
|
|
|
|
|
stat(2)
OSS System Calls Reference Manual
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.
st_nlink
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.
st_uid
For
Contains
Regular file
Directory
FIFO
AF_UNIX socket
/dev/null
/dev/tty
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 next. Values for Guardian
objects are described in Use on Guardian Objects, later in this
reference page.
st_gid
For
Contains
Regular file
Directory
FIFO
AF_UNIX socket
/dev/null
/dev/tty
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 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)
st_rdev
stat(2)
For
Contains
Regular file
Directory
FIFO
AF_UNIX socket
/dev/null
/dev/tty
Group ID of the file group
Group ID of the file group
Group ID of the file group
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.
st_size
For
Contains
Regular file
Directory
FIFO
AF_UNIX socket
/dev/null
/dev/tty
Undefined
Undefined
Undefined
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.
st_atime
For
Contains
Regular file
Directory
FIFO
AF_UNIX socket
/dev/null
/dev/tty
Size of the file in bytes
4096
0 (zero)
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.
527186-003
Hewlett-Packard Company
7−163
stat(2)
OSS System Calls Reference Manual
For
Contains
Regular file
Directory
FIFO
AF_UNIX socket
/dev/null
/dev/tty
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.
st_mtime
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
AF_UNIX socket
/dev/null
/dev/tty
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.
st_ctime
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
FIFO
AF_UNIX socket
/dev/null
/dev/tty
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.
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
Guardian
st_mode
in /G
File Type
File Type
Permissions
_Example
__________________________________________________________________
/G
vol
vol/subvol
vol/subvol/fileid
vol/#123
ztnt
ztnt/#pty0001
vol1/zyq00001
N/A
Disk volume
Subvolume
Disk file
Temporary disk file
Subtype 30 process
Subtype 30 process
with qualifier
Subvolume
Directory
Directory
Directory
Regular file
Regular file
Directory
Character special
r-xr-xr-x
rwxrwxrwx
rwxrwxrwx
See following text
See following text
--x--x--x
rw-rw-rw-
Directory
---------
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]
Search permission is denied for a component of the pathname
pointed to by the path parameter.
[EFAULT]
Either the buffer parameter or the path parameter points to a
location outside of the allocated address space of the process.
[EFSBAD]
The program attempted an operation involving a fileset with a
corrupted fileset catalog.
[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.
[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]
[ENOROOT]
527186-003
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 NonStop node, but communication with the remote node has
been lost.
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.
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:
•
7−168
The errno values [EFAULT], [EFSBAD], [ENOROOT], [ENXIO], and
[EOSSNOTRUNNING] can be returned by the stat( ) function.
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
Is a pathname that specifies any file within a mounted fileset.
buffer
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
527186-003
Fileset block size.
Hewlett-Packard Company
7−169
statvfs(2)
OSS System Calls Reference Manual
f_frsize
f_blocks
For
Contains
Regular file
Directory
FIFO
AF_UNIX socket
/dev/null
Object in /G
/G
/G/ztnt/#ptynn
/E
4096
4096
4096
4096
4096
4096
4096
4096
4096
Fundamental file system block size.
For
Contains
Regular file
Directory
FIFO
AF_UNIX socket
/dev/null
Object in /G
/G
/G/ztnt/#ptynn
/E
4096
4096
4096
4096
4096
4096
4096
4096
4096
Total number of blocks in fileset, in units of f_frsize.
For
Contains
Regular file
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.
Number of blocks on all volumes ever used
in the fileset.
Number of blocks on the volume containing the object.
0
0
0
Directory
FIFO
AF_UNIX socket
/dev/null
Object in /G
/G
/G/ztnt/#ptynn
/E
7−170
Hewlett-Packard Company
527186-003
System Functions (s and S)
f_bfree
statvfs(2)
Total number of free blocks in fileset.
For
Contains
Regular file
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
0
0
Directory
FIFO
AF_UNIX socket
/dev/null
Object in /G
/G
/G/ztnt/#ptynn
/E
f_bavail
Number of free blocks available to a process without appropriate
privileges.
For
Contains
Regular file
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
Directory
FIFO
AF_UNIX socket
/dev/null
Object in /G
/G
527186-003
Hewlett-Packard Company
7−171
statvfs(2)
OSS System Calls Reference Manual
/G/ztnt/#ptynn
/E
f_files
f_ffree
Total number of file serial numbers (inode numbers) in the
fileset.
For
Contains
Regular file
Directory
FIFO
AF_UNIX socket
/dev/null
Object in /G
/G
/G/ztnt/#ptynn
/E
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.
Number of inode numbers in the fileset.
The value of ULONG_MAX.
0
0
0
Total number of free file serial numbers (inode numbers) in the
fileset.
For
Contains
Regular file
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.
The value of ULONG_MAX.
0
0
0
Directory
FIFO
AF_UNIX socket
/dev/null
Object in /G
/G
/G/ztnt/#ptynn
/E
f_favail
7−172
0
0
Number of file serial numbers (inode numbers) available to a
process without appropriate privileges.
Hewlett-Packard Company
527186-003
System Functions (s and S)
statvfs(2)
For
Contains
Regular file
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.
The value of ULONG_MAX.
0
0
0
Directory
FIFO
AF_UNIX socket
/dev/null
Object in /G
/G
/G/ztnt/#ptynn
/E
f_fsid
Fileset identifier.
For
Contains
Regular file
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.
Directory
FIFO
AF_UNIX socket
/dev/null
Object in /G
/G
/G/ztnt/#ptynn
/E
f_basetype
527186-003
Type of file system.
Hewlett-Packard Company
7−173
statvfs(2)
OSS System Calls Reference Manual
f_flag
For
Contains
Regular file
Directory
FIFO
AF_UNIX socket
/dev/null
Object in /G
/G
/G/ztnt/#ptynn
/E
OSS
OSS
OSS
OSS
OSS
GUARDIAN
GUARDIAN
GUARDIAN
EXPAND
Bit mask indicating type of fileset access allowed.
For
Contains
Regular file
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.
2
3
2
3
Directory
FIFO
AF_UNIX socket
/dev/null
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)
f_namemax
f_fstr
statvfs(2)
Maximum number of character bytes in a filename within the
fileset.
For
Contains
Regular file
Directory
FIFO
AF_UNIX socket
/dev/null
Object in /G
/G
/G/ztnt/#ptynn
/E
248
248
248
248
248
8
7
7
7
Fileset pathname prefix string.
For
Contains
Regular 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/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
Directory
FIFO
AF_UNIX socket
/dev/null
Object in /G
/G
/G/ztnt/#ptynn
/E
f_bminavail
527186-003
Number of blocks free on the disk volume with the least space
remaining.
Hewlett-Packard Company
7−175
statvfs(2)
OSS System Calls Reference Manual
f_bmaxavail
For
Contains
Regular file
Directory
FIFO
AF_UNIX socket
/dev/null
Object in /G
/G
/G/ztnt/#ptynn
/E
Number of blocks.
Number of blocks.
Number of blocks.
Number of blocks.
Number of blocks.
Number of blocks.
0
0
0
Number of blocks free on the disk volume with the most space
remaining.
For
Contains
Regular file
Directory
FIFO
AF_UNIX socket
/dev/null
Object in /G
/G
/G/ztnt/#ptynn
/E
Number of blocks.
Number of blocks.
Number of blocks.
Number of blocks.
Number of blocks.
Number of blocks.
0
0
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]
Search permission is denied for a component of the path prefix
of the path parameter.
[EFAULT]
The buffer or path parameter points to a location outside of the
allocated address space of the process.
[EINTR]
The function was interrupted by a signal before any data arrived.
[EIO]
One of the following conditions occurred:
[ELOOP]
•
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 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.
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
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.
path2
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:
7−178
link( )
An error is returned if a symbolic link is named by the path2
parameter.
lstat( )
If the file specified is a symbolic link, the status of the link itself
is returned.
Hewlett-Packard Company
527186-003
System Functions (s and S)
symlink(2)
mknod( )
An error is returned if a symbolic link is named as the path
parameter.
open( )
An error is returned when O_CREAT and O_EXCL are both
specified and the path parameter specifies an existing symbolic
link.
readlink( )
This function applies only to symbolic links.
remove( )
A symbolic link can be removed by invoking the remove( )
function.
rename( )
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.
rmdir( )
An error is returned if a symbolic link is named as the path
parameter.
unlink( )
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]
The path specified by the path2 parameter already exists.
[EFAULT]
Either the path1 or the path2 parameter points outside the
process’s allocated address space.
[EFSBAD]
The fileset catalog for one of the filesets involved in the operation is corrupt.
[EIO]
An input/output error occurred during a read from or write to the
fileset.
[ELOOP]
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]
7−180
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.
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:
•
527186-003
The errno values [EFAULT], [EFSBAD], [ENOROOT], [ENOTSUP],
[ENXIO], and [EOSSNOTRUNNING] can be returned.
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 ENDTRANSACTION 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
(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.
tag
(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-opnum, 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 (FEScSendOperationAborted) 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 Pathsend 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-opnum, 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
(Optional) If provided, must contain 0 (zero) to indicate a waited operation.
This parameter is provided for compatibility with the Guardian
SERVERCLASS_SEND_ procedure.
tag
(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 Pathsend 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 (FEScInvalidFlagsValue).
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 (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_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 (FEScError) and SPT_SERVERCLASS_SEND_INFO_( ) will show Pathsend error 917 (FEScServerClassTmfViolation) 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
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.
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.
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.
envp[ ]
Specifies an array of character pointers to null-terminated strings that describe
the environment for the new process.
pe_parms
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.
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 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 propagat