f2d50bbf9c
This change implements a dependency tracking daemon(7) system in init with overridable init(5) configuration, parallel startup, readiness signaling, rotating logs, reliable stopping, and handling of leaked processes. The /etc/init/target file is replaced by the new /etc/init/default per the new init(5) format. The old configuration is migrated upon upgrade using an upgrade hook. extfs(8) now signals readiness using READYFD for fast mounting. Filesystems that fail to be repaired are now mounted read-only. The mounting and filesystem checking code is synchronized with sysinstall. The duplicated array_add utility function now protects against overflows. tix-iso-bootconfig(8) gains the --init-target option. tix-iso-liveconfig(8) gains the --daemons option.
304 lines
8.1 KiB
Groff
304 lines
8.1 KiB
Groff
.Dd March 28, 2022
|
|
.Dt PORTABILITY 7
|
|
.Os
|
|
.Sh NAME
|
|
.Nm portability
|
|
.Nd standard library portability information
|
|
.Sh DESCRIPTION
|
|
This manual documents replacements for interfaces not available in the standard
|
|
library or with special portability notes.
|
|
.Pp
|
|
Software written for other operating systems can be ported by replacing uses of
|
|
obsolete interfaces with the modern replacements and working around any missing
|
|
functionality.
|
|
The standard library attemps to implement the relevant parts of the C and POSIX
|
|
standards with useful extensions and tends to omit non-standard extensions found
|
|
on other operating systems whenever standard interfaces exists.
|
|
.Ss alloca
|
|
.Xr alloca 3
|
|
and variable length arrays are implemented by the compiler, however the main
|
|
thread stack size is fixed and does not grow unlike other operating systems, and
|
|
large stack uses should instead use
|
|
.Xr malloc 3
|
|
or set the stack size explicitly for another thread using
|
|
.Xr pthread_attr_setstacksize 2 .
|
|
.Ss asctime, asctime_r
|
|
.Xr strftime 3
|
|
is the standard replacement.
|
|
.Ss bcopy
|
|
.Xr memcpy 3
|
|
is the standard replacement.
|
|
Note how the order of the source and destination parameters is swapped.
|
|
.Ss bzero
|
|
.Xr memset 3
|
|
is the standard replacement.
|
|
.Ss caddr_t
|
|
.Vt void *
|
|
is the standard type.
|
|
.Ss clock
|
|
.Xr clock 3
|
|
is implemented but can overflow, and
|
|
.Xr clock_gettime 2
|
|
.Dv CLOCK_PROCESS_CPUTIME_ID
|
|
is the modern replacement with nanosecond precision.
|
|
.Ss ctime, ctime_r
|
|
.Xr strftime 3
|
|
is the standard replacement.
|
|
.Ss daemon
|
|
Daemons should not background by double forking but rather stay in the
|
|
foreground as described in
|
|
.Xr daemon 7
|
|
and be managed by
|
|
.Xr init 8 .
|
|
.Ss __dead
|
|
.Dv noreturn
|
|
from
|
|
.In stdnoreturn.h
|
|
is the modern standard replacement or the
|
|
.Sy __attribute__((noreturn))
|
|
extension can be used.
|
|
.Ss flock, fcntl F_UNLCK, F_WRLCK, F_GETLK, F_SETLK, F_SETLKW, lockf
|
|
POSIX advisory locks are not implemented due to their flawed design of being
|
|
process-wide instead of being per file description.
|
|
The superior
|
|
.Xr flock 2
|
|
is not currently implemented.
|
|
It might be safe enough to omit the file locking as a workaround.
|
|
.Ss ftime
|
|
.Xr clock_gettime 2
|
|
is the standard replacement.
|
|
.Ss getdtablesize
|
|
The file descriptor table is unbounded and file descriptors above a certain
|
|
value can be closed using
|
|
.Xr closefrom 2
|
|
and iterated using
|
|
.Xr psctl 2 .
|
|
.Ss getgroups, setgroups, initgroups
|
|
Supplementary groups are not implemented yet.
|
|
It may be possible to remove invocations as a workaround.
|
|
.Ss gethostbyaddr
|
|
.Xr getnameinfo 3
|
|
is the standard modern replacement.
|
|
.Ss gethostbyname
|
|
.Xr getaddrinfo 3
|
|
is the standard modern replacement.
|
|
.Ss getitimer, setitimer
|
|
.Xr timer_create 2
|
|
is the modern standard replacement.
|
|
.Ss getpgrp, setpgrp
|
|
.Xr getpgid 3
|
|
and
|
|
.Xr setpgid 3
|
|
are the standard portable replacements without disagreement on the function
|
|
signatures.
|
|
.Ss gettimeofday
|
|
.Xr gettimeofday 2
|
|
is implemented but the second parameter is defunct and is typed
|
|
.Vt void *
|
|
per POSIX instead of
|
|
.Vt struct timezone * .
|
|
.Xr clock_gettime 2
|
|
is the modern replacement with nanosecond precision.
|
|
.Ss gid_t
|
|
.Vt gid_t
|
|
is 64-bit unsigned and can be formatted portably cast to a
|
|
.Vt uintmax_t
|
|
using
|
|
.Dq %ju .
|
|
.Ss inet_addr, inet_aton
|
|
.Xr inet_pton 3
|
|
and
|
|
.Xr getaddrinfo 3
|
|
are the modern standard replacements, however they don't support the unusual
|
|
IPv4 notations.
|
|
.Ss inet_ntoa
|
|
.Xr inet_ntop 3
|
|
and
|
|
.Xr getnameinfo 3
|
|
are the modern standard replacements.
|
|
.Ss <limits.h>
|
|
.In limits.h
|
|
is currently implemented by the compiler instead of the standard library and it
|
|
does not define everything required by POSIX.
|
|
.In sortix/limits.h
|
|
can be included instead as a temporary workaround if the required definitions
|
|
are absent.
|
|
.Ss makedev, major, minor
|
|
The kernel does not have a concept of major and minor device numbers.
|
|
.Ss mkfifo
|
|
.Xr mkfifo 2
|
|
named pipes are not currently implemented but unnamed pipes are available using
|
|
.Xr pipe 2 ,
|
|
or alternatively
|
|
.Dv AF_UNIX
|
|
sockets can be used instead.
|
|
.Ss mknod
|
|
Devices in the
|
|
.Pa /dev
|
|
filesystem are created by the kernel and cannot be manually created.
|
|
.Ss mmap
|
|
.Xr mmap 2
|
|
is implemented, but
|
|
.Dv MAP_SHARED
|
|
shared memory mappings are not implemented yet.
|
|
.Ss off_t
|
|
.Vt off_t
|
|
is 64-bit signed and can be formatted portably cast to an
|
|
.Vt intmax_t
|
|
using
|
|
.Dq %jd .
|
|
.Ss PATH_MAX
|
|
The
|
|
.Dv PATH_MAX
|
|
limit does not currently exist and may be added in the future.
|
|
Applications should be written as if this limit does not exist, but if required,
|
|
it can be defined to 4096 as a fallback.
|
|
.Ss pid_t
|
|
.Vt pid_t
|
|
is 64-bit signed and can be formatted portably cast to an
|
|
.Vt intmax_t
|
|
using
|
|
.Dq %jd .
|
|
.Ss poll
|
|
.Xr poll 2
|
|
is implemented in
|
|
.In poll.h
|
|
per POSIX, however some operating systems have a
|
|
.In sys/poll.h
|
|
alias which is not implemented.
|
|
.Ss printf
|
|
.Xr printf 3
|
|
is implemented, however floating point formatting is not currently implemented
|
|
and the format specifier will instead be output verbatim.
|
|
Position parameters are also not implemented yet.
|
|
.Ss pthread_cancel
|
|
Pthread cancellation is not implemented and threads instead have to
|
|
.Xr pthread_exit 3
|
|
voluntarily.
|
|
.Ss pthread_kill
|
|
Sending a signal to a particular thread is not implemented.
|
|
.Ss putenv
|
|
.Xr setenv 3
|
|
is the standard replacement.
|
|
Note how the string provided could technically be modified at a later time.
|
|
.Ss rand, srand
|
|
.Xr rand 3
|
|
and
|
|
.Xr srand 3
|
|
are implemented, however invocations will warn that the functions are not
|
|
random, and
|
|
.Xr arc4random 3 ,
|
|
.Xr arc4random_uniform 3 ,
|
|
or
|
|
.Xr arc4random_buf 3
|
|
should be used instead for random numbers.
|
|
.Ss realpath
|
|
.Xr realpath 3
|
|
with a non-null second parameter is undefined behavior as there is no
|
|
.Dv PATH_MAX
|
|
limit, and should always be invoked with a null second parameter which allocates
|
|
a destination buffer of the appropriate size using
|
|
.Xr malloc 3 .
|
|
.Ss <resolv.h>
|
|
.In resolv.h
|
|
is currently not implemented and
|
|
.Xr getaddrinfo 2
|
|
can be used instead.
|
|
.Ss sbrk
|
|
.Xr malloc 3
|
|
and
|
|
.Xr mmap 2
|
|
are the standard interfaces for memory allocation.
|
|
.Ss select
|
|
.Xr select 2
|
|
is implemented, but is defined in
|
|
.In sys/select.h
|
|
instead of
|
|
.In sys/time.h
|
|
per POSIX, however the superior
|
|
.Xr poll 2
|
|
should be used instead as the
|
|
.Vt fdset_t
|
|
type overflows on file descriptors whose value is too large.
|
|
.Ss sigaction SA_RESTART
|
|
Restarting system calls after signal delivery is not currently implemented and
|
|
system calls instead fail with
|
|
.Er EINTR .
|
|
.Ss socklen_t
|
|
.Vt socklen_t
|
|
is typedef to
|
|
.Vt size_t
|
|
instead of
|
|
.Vt int
|
|
or
|
|
.Vt unsigned int
|
|
as on other operating systems.
|
|
.Ss sprintf
|
|
.Xr sprintf 3
|
|
is implemented, however invocations will warn the function is dangerous as it
|
|
does not know the size of the destination buffer and may buffer overflow if the
|
|
output is unexpectedly large.
|
|
.Xr snprintf 3
|
|
should be use instead as the destination buffer size should always be known,
|
|
otherwise the invocation is suspicious.
|
|
The superior alternative is to combine allocation and initialization using
|
|
.Xr asprintf 3 .
|
|
.Ss strptime
|
|
.Xr strptime 3
|
|
is not currently implemented.
|
|
.Ss <sys/param.h>
|
|
.In sys/param.h
|
|
is not implemented as there is little agreement on what it's supposed to contain
|
|
and all the contents have standard replacements or can be provided by the
|
|
application itself.
|
|
Inclusions are almost always unnecessary and can be removed.
|
|
.Ss times
|
|
.Xr times 2
|
|
is implemented, however the
|
|
.Vt clock_t
|
|
type may overflow, and the
|
|
.Xr timens 2
|
|
non-standard extension with
|
|
.Vt struct timespec
|
|
precision can be used instead.
|
|
.Ss time_t
|
|
.Vt time_t
|
|
is 64-bit signed and can be formatted portably cast to an
|
|
.Vt intmax_t
|
|
using
|
|
.Dq %ji
|
|
or with
|
|
.Xr strftime 3
|
|
and such.
|
|
.Pp
|
|
.Dv CLOCK_REALTIME
|
|
counts the number of seconds since the epoch including leap seconds, unlike
|
|
other operating systems and in violation of POSIX.
|
|
.Ss u_char, u_short, u_int, u_long
|
|
.Vt unsigned char ,
|
|
.Vt unsigned short ,
|
|
.Vt unsigned int ,
|
|
and
|
|
.Vt unsigned long
|
|
are the standard types.
|
|
Applications can supply the typedefs themselves if desired.
|
|
.Ss uid_t
|
|
.Vt uid_t
|
|
is 64-bit unsigned and can be formatted portably cast to a
|
|
.Vt uintmax_t
|
|
using
|
|
.Dq %ju .
|
|
.Ss u_int8_t, u_int16_t, u_int32_t, u_int64_t
|
|
.Vt uint8_t ,
|
|
.Vt uint16_t ,
|
|
.Vt uint32_t ,
|
|
and
|
|
.Vt uint64_t
|
|
are the standard types.
|
|
Applications can supply the typedefs themselves if desired.
|
|
.Ss wait3, wait4
|
|
.Xr waitpid 2
|
|
is the standard replacement.
|
|
.Sh SEE ALSO
|
|
.Xr porting 7
|