From owner-freebsd-arch@FreeBSD.ORG Sat Jan 11 02:27:56 2014 Return-Path: Delivered-To: freebsd-arch@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 2E1EF87E; Sat, 11 Jan 2014 02:27:56 +0000 (UTC) Received: from mail109.syd.optusnet.com.au (mail109.syd.optusnet.com.au [211.29.132.80]) by mx1.freebsd.org (Postfix) with ESMTP id B329A1646; Sat, 11 Jan 2014 02:27:55 +0000 (UTC) Received: from c122-106-144-87.carlnfd1.nsw.optusnet.com.au (c122-106-144-87.carlnfd1.nsw.optusnet.com.au [122.106.144.87]) by mail109.syd.optusnet.com.au (Postfix) with ESMTPS id CB157D60B7A; Sat, 11 Jan 2014 13:27:51 +1100 (EST) Date: Sat, 11 Jan 2014 13:27:50 +1100 (EST) From: Bruce Evans X-X-Sender: bde@besplex.bde.org To: Adrian Chadd Subject: Re: Using sys/types.h types in sys/socket.h In-Reply-To: Message-ID: <20140111123050.Q940@besplex.bde.org> References: <9C1291B5-215B-440E-B8B0-6308840F755C@bsdimp.com> <5821DA91-E9C7-4D1A-A108-63E74CFF1FC5@bsdimp.com> <20140108152632.L969@besplex.bde.org> <20140109092602.M957@besplex.bde.org> <20140110222640.F2338@besplex.bde.org> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed X-Optus-CM-Score: 0 X-Optus-CM-Analysis: v=2.1 cv=HZAtEE08 c=1 sm=1 tr=0 a=p/w0leo876FR0WNmYI1KeA==:117 a=PO7r1zJSAAAA:8 a=n4PiHyf99_4A:10 a=kj9zAlcOel0A:10 a=JzwRw_2MAAAA:8 a=zprIhm_aaxwA:10 a=r4xjbp9k3fJWGc56tWsA:9 a=1b5EBEOVRRPCUfEE:21 a=5qZ5JmMQtflom2lH:21 a=CjuIK1q_8ugA:10 Cc: "freebsd-arch@freebsd.org" X-BeenThere: freebsd-arch@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: Discussion related to FreeBSD architecture List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 11 Jan 2014 02:27:56 -0000 On Fri, 10 Jan 2014, Adrian Chadd wrote: > On 10 January 2014 03:38, Bruce Evans wrote: > ... >> This also has the unrelated change of using __ufoo instead of ufoo. I >> think that is only correct if the types are supposed to be almost opaque, >> with the details not part of the API. > > Peter raised a point on irc - if I define uint32_t/uintptr_t in the > header, then code that includes sys/socket.h will be able to use > uint32_t / uintptr_t without including sys/types.h. > > What should be done there? It depends on whether you want to make these types part of the API. If they are part of the API, then they should be documented. Such documentation is rarely done. FreeBSD's socket(2) man page is so out of date that it still documents the 1980's requirement that sys/types.h must be included before sys/socket.h. POSIX fixed this when it adopted socket(2) in 2001 or earlier, and FreeBSD's sys/socket.h was updated to not need sys/types.h in 2002/08/21, but the man page still documents the old requirement. The man page also still doesn't claim any POSIX conformance. So strictly, the POSIX cleanups are not part of the FreeBSD API and FreeBSD programs shouldn't depend on them. Similarly in the man pages accept(2), bind(2), bindat(2), connect(2), connectat(2), getpeername(2), getsockname(2), getsockopt(2), listen(2), recv(2), sctp_generic_recvmsg(2), sctp_generic_sendmsg(2), sctp_peeloff(2), send(2), sendfile(2), shutdown(2), socketpair(2), ethers(3), gai_strerror(3), getaddrinfo(3), getipnodebyname(3), getnameinfo(3), if_nametoindex(3), inet(3), inet_net(3), link_addr(3), sctp_bindx(3), sctp_connectx(3), sctp_freepaddrs(3), sctp_getaddrlen(3), sctp_getassocid(3), sctp_opt_info(3), sctp_rcvmsg(3), sctp_send(3), sctp_sendmsg(3) but not in setfib(2), sockatmark(3), sourcefilter(3). The 1980's API has been copied into almost all new man pages. Some of these have includes other than of sys/socket.h and it is likely that most of the non-POSIX headers still depend on symbols in sys/types.h other than the ones provided by FreeBSD extensions in sys/socket.h. I didn't notice any documenation of just sys/socket.h or much about the types in it. For example, POSIX.1-2001 specifies socklen_t as being an integer type of width at least 32 bits, and recommends that applications not try to use values larger than 2**31-1 in it. The restriction follows from the type possibly being int32_t. In FreeBSD, it is actually uint32_t, so values up to 2**32-1 work, but assuming this would be unportable. 4.4BSD didn't have socklen_t, and it mostly used int instead, so assuming this was unportable even within BSD. All of these points seems to be missing in FreeBSD man pages. Similarly in most syscall man pages starting with read(2), except many of them claim POSIX conformance. Bruce