Rewrite types(5) as per perry@'s suggestion from few years back ("XXX this

document is rather musty. It needs a general update."). Also move it to the
right section from section 5. Ok wiz@.

To minimize maintenance costs, the content is mostly jargon around The
Standard. Only few NetBSD-specific types are mentioned as an example.
This commit is contained in:
jruoho 2010-04-22 06:48:28 +00:00
parent 9f8746b55e
commit 526aa19c52
6 changed files with 234 additions and 189 deletions

View File

@ -1,4 +1,4 @@
# $NetBSD: mi,v 1.1434 2010/04/21 18:04:38 jruoho Exp $
# $NetBSD: mi,v 1.1435 2010/04/22 06:48:28 jruoho Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
#
@ -8219,6 +8219,7 @@
./usr/share/man/cat3/ttyslot.0 comp-c-catman .cat
./usr/share/man/cat3/ttyunlock.0 comp-c-catman .cat
./usr/share/man/cat3/twalk.0 comp-c-catman .cat
./usr/share/man/cat3/types.0 comp-c-catman .cat
./usr/share/man/cat3/tzset.0 comp-c-catman .cat
./usr/share/man/cat3/tzsetwall.0 comp-c-catman .cat
./usr/share/man/cat3/ualarm.0 comp-c-catman .cat
@ -13946,6 +13947,7 @@
./usr/share/man/html3/ttyslot.html comp-c-htmlman html
./usr/share/man/html3/ttyunlock.html comp-c-htmlman html
./usr/share/man/html3/twalk.html comp-c-htmlman html
./usr/share/man/html3/types.html comp-c-htmlman html
./usr/share/man/html3/tzset.html comp-c-htmlman html
./usr/share/man/html3/tzsetwall.html comp-c-htmlman html
./usr/share/man/html3/ualarm.html comp-c-htmlman html
@ -19743,6 +19745,7 @@
./usr/share/man/man3/ttyslot.3 comp-c-man .man
./usr/share/man/man3/ttyunlock.3 comp-c-man .man
./usr/share/man/man3/twalk.3 comp-c-man .man
./usr/share/man/man3/types.3 comp-c-man .man
./usr/share/man/man3/tzset.3 comp-c-man .man
./usr/share/man/man3/tzsetwall.3 comp-c-man .man
./usr/share/man/man3/ualarm.3 comp-c-man .man

View File

@ -1,4 +1,4 @@
# $NetBSD: mi,v 1.1203 2010/04/10 20:52:14 pooka Exp $
# $NetBSD: mi,v 1.1204 2010/04/22 06:48:28 jruoho Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
#
@ -1896,7 +1896,7 @@
./usr/share/man/cat5/transport.0 man-postfix-catman postfix,.cat
./usr/share/man/cat5/ttyaction.0 man-sys-catman .cat
./usr/share/man/cat5/ttys.0 man-sys-catman .cat
./usr/share/man/cat5/types.0 man-c-catman .cat
./usr/share/man/cat5/types.0 man-obsolete obsolete
./usr/share/man/cat5/tzfile.0 man-sys-catman .cat
./usr/share/man/cat5/ucontext.0 man-obsolete obsolete
./usr/share/man/cat5/usermgmt.conf.0 man-sys-catman .cat
@ -4456,7 +4456,7 @@
./usr/share/man/html5/transport.html man-postfix-htmlman postfix,html
./usr/share/man/html5/ttyaction.html man-sys-htmlman html
./usr/share/man/html5/ttys.html man-sys-htmlman html
./usr/share/man/html5/types.html man-c-htmlman html
./usr/share/man/html5/types.html man-obsolete obsolete
./usr/share/man/html5/tzfile.html man-sys-htmlman html
./usr/share/man/html5/usermgmt.conf.html man-sys-htmlman html
./usr/share/man/html5/utmp.html man-sys-htmlman html
@ -6986,7 +6986,7 @@
./usr/share/man/man5/transport.5 man-postfix-man postfix,.man
./usr/share/man/man5/ttyaction.5 man-sys-man .man
./usr/share/man/man5/ttys.5 man-sys-man .man
./usr/share/man/man5/types.5 man-c-man .man
./usr/share/man/man5/types.5 man-obsolete obsolete
./usr/share/man/man5/tzfile.5 man-sys-man .man
./usr/share/man/man5/ucontext.5 man-obsolete obsolete
./usr/share/man/man5/usermgmt.conf.5 man-sys-man .man

View File

@ -1,11 +1,11 @@
# $NetBSD: Makefile,v 1.48 2010/04/21 18:04:38 jruoho Exp $
# $NetBSD: Makefile,v 1.49 2010/04/22 06:48:29 jruoho Exp $
# @(#)Makefile 8.2 (Berkeley) 12/13/93
MAN= _DIAGASSERT.3 __CONCAT.3 __UNCONST.3 CMSG_DATA.3 \
__arraycount.3 assert.3 bits.3 bitstring.3 dlfcn.3 end.3 \
fast_divide32.3 gcq.3 intro.3 inttypes.3 iso646.3 offsetof.3 queue.3 \
rb.3 stdarg.3 stdbool.3 stddef.3 stdint.3 stdlib.3 sysexits.3 \
tgmath.3 timeradd.3 tree.3 varargs.3
tgmath.3 timeradd.3 tree.3 types.3 varargs.3
USETBL= # used by queue.3

222
share/man/man3/types.3 Normal file
View File

@ -0,0 +1,222 @@
.\" $NetBSD: types.3,v 1.1 2010/04/22 06:48:29 jruoho Exp $
.\"
.\" Copyright (c) 2010 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Jukka Ruohonen.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.\" Copyright (c) 1980, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" @(#)types.5 8.1 (Berkeley) 6/5/93
.\"
.Dd March 22, 2010
.Dt TYPES 3
.Os
.Sh NAME
.Nm types
.Nd standard system data types
.Sh SYNOPSIS
.In sys/types.h
.Sh DESCRIPTION
The
.In sys/types.h
header contains the common data types used in the system.
Although these are meant to be used within the kernel,
most of the system data types are accessible also to user code.
A companion header
.In sys/param.h ,
typically used in the kernel,
includes
.In sys/types.h
and provides additional types as well as other facilities.
.Ss Standard Types
The following standards-compliant data types are defined:
.Pp
.Bl -column -offset indent \
"suseconds_t " "file system block counts " "clock_settime(3) "
.It Sy Type Ta Sy Typical use Ta Sy Example
.It Va blkcnt_t Ta file block counts Ta Xr stat 2
.It Va blksize_t Ta block sizes Ta Xr stat 2
.It Va clock_t Ta system clock ticks Ta Xr clock 3
.It Va clockid_t Ta clock IDs Ta Xr clock_settime 2
.It Va dev_t Ta device IDs Ta Xr devname 3
.It Va fsblkcnt_t Ta file system block counts Ta -
.It Va fsfilcnt_t Ta file system file counts Ta -
.It Va gid_t Ta group IDs Ta Xr getgid 2
.It Va id_t Ta general identifier Ta Xr pset 3
.It Va ino_t Ta file serial numbers Ta Xr fs 5
.It Va key_t Ta interprocess communication Ta Xr ftok 3
.It Va mode_t Ta file attributes Ta Xr stat 2
.It Va nlink_t Ta link counts Ta Xr stat 2
.It Va off_t Ta file sizes Ta Xr fseek 3
.It Va pid_t Ta process and group IDs Ta Xr getpid 2
.It Va size_t Ta size of objects Ta Xr stddef 3
.It Va ssize_t Ta a count of bytes Ta Xr write 2
.It Va suseconds_t Ta microseconds Ta Xr gettimeofday 2
.It Va time_t Ta time in seconds Ta Xr time 3
.It Va timer_t Ta timer IDs Ta Xr timer_create 2
.\"
.\" XXX: Following are undefined in NetBSD at the time of writing:
.\"
.\".It Va trace_attr_t Ta trace stream attributes Ta -
.\".It Va trace_event_id_t Ta trace event type Ta -
.\".It Va trace_event_set_t Ta trace event type set Ta -
.\".It Va trace_id_t Ta trace stream ID Ta -
.It Va uid_t Ta user IDs Ta Xr setuid 2
.It Va useconds_t Ta time in microseconds Ta Xr usleep 3
.El
.Pp
In addition, when included in user applications,
.In sys/types.h
includes
.In pthread.h ,
and thus it defines also the types used in the
.Tn POSIX
Threads Library,
.Xr pthread 3 .
.Pp
Each described type may vary across machines and operating systems.
Only the following properties are guaranteed by the
.St -p1003.1-2001
standard:
.Bl -enum -offset indent
.It
The type
.Em ssize_t
is capable of storing integer values at least in the range [ -1,
.Dv SSIZE_MAX
].
.It
The type
.Em useconds_t
is an unsigned integer capable of storing
values at least in the range [ 0, 1000000 ].
.It
The type
.Em suseconds_t
is a signed integer capable of storing
values at least in the range [ -1, 1000000 ].
.It
The
.Em time_t
and
.Em clock_t
types are either integers or real-floating types.
.It
The following types are integers:
.Em gid_t ,
.Em id_t ,
.Em mode_t ,
.Em nlink_t ,
and
.Em uid_t .
.It
The following types are signed integers:
.Em blkcnt_t ,
.Em blksize_t ,
.Em off_t ,
.Em pid_t ,
and
.Em ssize_t .
.It
The following types are unsigned integers:
.Em fsblkcnt_t ,
.Em fsfilcnt_t ,
.Em ino_t ,
and
.Em size_t .
.El
.Sh NetBSD-specific Types
In addition to the standard types, the
.In sys/types.h
defines some data types specific to
.Nx .
These are mostly used in the kernel.
A portable implementation should not rely
on these types to be available in other systems.
Examples include:
.Bl -column -offset indent \
"suseconds_t " "file system block counts " "clock_settime(3) "
.It Sy Type Ta Sy Typical use Ta Sy Example
.It Va cpuid_t Ta CPU ID Ta Xr cpuset 3
.It Va daddr_t Ta disk address Ta Xr buffercache 9
.It Va devmajor_t Ta major device number Ta Xr getdevmajor 3
.It Va lwp_t Ta typedef of Va struct lwp Ta Xr kthread 9
.It Va u_quad_t Ta synonym for Va uint64_t Ta Xr strtouq 3
.El
.Pp
It can be noted that the standard
.Dq C99 types
described in
.Xr stdint 3
are preferred to the older fixed size integer types prefixed with an
.Dq u_
(in another words,
.Va uint32_t
should be used instead of
.Va u_int32_t ) .
.Sh SEE ALSO
.Xr stdbool 3 ,
.Xr stddef 3 ,
.Xr stdint 3 ,
.Xr stdlib 3
.Sh STANDARDS
The
.In sys/types.h
header conforms to
.St -p1003.1-2001
with respect to the described standard types.
.Sh HISTORY
The
.In sys/types.h
header first appeared in
.At v7 .
In the current form the header appeared in
.Nx 0.9 .

View File

@ -1,4 +1,4 @@
# $NetBSD: Makefile,v 1.62 2009/07/25 16:20:11 mbalmer Exp $
# $NetBSD: Makefile,v 1.63 2010/04/22 06:48:28 jruoho Exp $
# @(#)Makefile 8.1 (Berkeley) 6/5/93
# missing: dump.5 plot.5
@ -15,7 +15,7 @@ MAN= a.out.5 acct.5 ar.5 boot.cfg.5 \
printcap.5 protocols.5 ranlib.5 rc.conf.5 remote.5 \
resolv.conf.5 route.conf.5 rpc.5 \
security.conf.5 services.5 shells.5 \
stab.5 statvfs.5 sysctl.conf.5 ttyaction.5 types.5 \
stab.5 statvfs.5 sysctl.conf.5 ttyaction.5 \
utmp.5 utmpx.5 veriexec.5 weekly.conf.5 wscons.conf.5
MLINKS= dir.5 dirent.5 fs.5 inode.5 hosts.equiv.5 rhosts.5

View File

@ -1,180 +0,0 @@
.\" $NetBSD: types.5,v 1.13 2010/03/22 18:58:32 joerg Exp $
.\"
.\" Copyright (c) 1980, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" @(#)types.5 8.1 (Berkeley) 6/5/93
.\"
.Dd December 26, 2005
.Dt TYPES 5
.Os
.Sh NAME
.Nm types
.Nd system data types
.Sh SYNOPSIS
.In sys/types.h
.Sh DESCRIPTION
The file
.In sys/types.h
contains the defined data types used in the kernel (most are
used throughout the system).
.Pp
Note that in
.Nx
code, when an integer of a specific width is needed, the C99
style
.Vt int8_t, uint8_t, int16_t, uint16_t, int32_t, uint32_t, int64_t, uint64_t
should be used.
The old
.Bx
style
.Vt u_int8_t, u_int16_t, u_int32_t, u_int64_t
are deprecated.
.Bd -literal
#ifndef _SYS_TYPES_H_
#define _SYS_TYPES_H_
/* Machine type dependent parameters. */
#include \*[Lt]machine/types.h\*[Gt]
#include \*[Lt]machine/ansi.h\*[Gt]
#include \*[Lt]machine/endian.h\*[Gt]
#if !defined(_POSIX_SOURCE) \*[Am]\*[Am] !defined(_XOPEN_SOURCE)
typedef unsigned char u_char;
typedef unsigned short u_short;
typedef unsigned int u_int;
typedef unsigned long u_long;
typedef unsigned char unchar; /* Sys V compatibility */
typedef unsigned short ushort; /* Sys V compatibility */
typedef unsigned int uint; /* Sys V compatibility */
typedef unsigned long ulong; /* Sys V compatibility */
#endif
typedef uint64_t u_quad_t; /* quads */
typedef int64_t quad_t;
typedef quad_t * qaddr_t;
typedef char * caddr_t; /* core address */
typedef int32_t daddr_t; /* disk address */
typedef int32_t dev_t; /* device number */
typedef uint32_t fixpt_t; /* fixed point number */
typedef uint32_t gid_t; /* group id */
typedef uint32_t ino_t; /* inode number */
typedef long key_t; /* IPC key (for Sys V IPC) */
typedef uint16_t mode_t; /* permissions */
typedef uint16_t nlink_t; /* link count */
typedef quad_t off_t; /* file offset */
typedef int32_t pid_t; /* process id */
typedef quad_t rlim_t; /* resource limit */
typedef int32_t segsz_t; /* segment size */
typedef int32_t swblk_t; /* swap offset */
typedef uint32_t uid_t; /* user id */
#if !defined(_POSIX_SOURCE) \*[Am]\*[Am] !defined(_XOPEN_SOURCE)
/* Major, minor numbers, dev_t's. */
#define major(x) ((int32_t)(((uint32_t)(x) \*[Gt]\*[Gt] 8) \*[Am] 0xff))
#define minor(x) ((int32_t)((x) \*[Am] 0xff))
#define makedev(x,y) ((dev_t)(((x) \*[Lt]\*[Lt] 8) | (y)))
#endif
#ifdef _BSD_CLOCK_T_
typedef _BSD_CLOCK_T_ clock_t;
#undef _BSD_CLOCK_T_
#endif
#ifdef _BSD_SIZE_T_
typedef _BSD_SIZE_T_ size_t;
#undef _BSD_SIZE_T_
#endif
#ifdef _BSD_SSIZE_T_
typedef _BSD_SSIZE_T_ ssize_t;
#undef _BSD_SSIZE_T_
#endif
#ifdef _BSD_TIME_T_
typedef _BSD_TIME_T_ time_t;
#undef _BSD_TIME_T_
#endif
#ifdef _BSD_CLOCKID_T_
typedef _BSD_CLOCKID_T_ clockid_t;
#undef _BSD_CLOCKID_T_
#endif
#ifdef _BSD_TIMER_T_
typedef _BSD_TIMER_T_ timer_t;
#undef _BSD_TIMER_T_
#endif
#if !defined(_POSIX_SOURCE) \*[Am]\*[Am] !defined(_XOPEN_SOURCE)
#define NBBY 8 /* number of bits in a byte */
/*
* Select uses bit masks of file descriptors in longs. These macros
* manipulate such bit fields (the filesystem macros use chars).
* FD_SETSIZE may be defined by the user, but the default here should
* be enough for most uses.
*/
#ifndef FD_SETSIZE
#define FD_SETSIZE 256
#endif
typedef int32_t fd_mask;
#define NFDBITS (sizeof(fd_mask) * NBBY) /* bits per mask */
#ifndef howmany
#define howmany(x, y) (((x) + ((y) - 1)) / (y))
#endif
typedef struct fd_set {
fd_mask fds_bits[howmany(FD_SETSIZE, NFDBITS)];
} fd_set;
#define FD_SET(n, p) ((p)-\*[Gt]fds_bits[(n)/NFDBITS] |= (1 \*[Lt]\*[Lt] ((n) % NFDBITS)))
#define FD_CLR(n, p) ((p)-\*[Gt]fds_bits[(n)/NFDBITS] \*[Am]= ~(1 \*[Lt]\*[Lt] ((n) % NFDBITS)))
#define FD_ISSET(n, p) ((p)-\*[Gt]fds_bits[(n)/NFDBITS] \*[Am] (1 \*[Lt]\*[Lt] ((n) % NFDBITS)))
#define FD_COPY(f, t) memcpy(t, f, sizeof(*(f)))
#define FD_ZERO(p) memset(p, 0, sizeof(*(p)))
#endif /* !defined(_POSIX_SOURCE) ... */
#endif /* !_SYS_TYPES_H_ */
.Ed
.Sh SEE ALSO
.Xr lseek 2 ,
.Xr select 2 ,
.Xr truncate 2 ,
.Xr byteorder 3 ,
.Xr time 3 ,
.Xr fs 5
.Sh HISTORY
A
.Nm
file appeared in
.At v7 .